record_email_send()

Send an email logged on a record's thread, exactly like the UI's email-on-record feature: it creates an email_out comment, sets a token Reply-To so replies thread back onto the record, and can attach the record's files. Posted as the System user.

For a plain fire-and-forget email with no record link, use smtp_email_send() instead.

Syntax

record_email_send(connection, spec, table, recordId, opts=[])

Parameters

Name	Type	Required	Description
`connection`	string	yes	Name of the SMTP integration connection to send through.
`spec`	array	yes	The email (see keys below).
`table`	string	yes	Table name or database table id of the record.
`recordId`	int	yes	The record's primary key.
`opts`	array	no	Options. `["silent" => true]` logs the email on the thread without notifying the record's followers (mentions and assigned-user notifications still fire).

spec keys: to (string or list: recipient emails or a user field), subject, html (body), from? ("Name <email>"; defaults to the connection's sender identity), attach_field? (a file field id whose files to attach, or a signature field id, which attaches its certificate of completion), attach_pattern? (glob like *.pdf, comma-separated allowed; file fields only), attachments? (list of in-memory attachments built with email_attachment(), stored in the table's file storage and shown on the logged email comment).

Returns

true once queued. Throws if the connection, From address, or recipients are missing/invalid.

Example

record_email_send("Main SMTP", [
    "to"      => $record["email"],
    "subject" => "Your invoice " . $record["number"],
    "html"    => "<p>Hi " . $record["name"] . ", your invoice is attached.</p>",
    "attach_field"   => "documents",
    "attach_pattern" => "*.pdf"
], "invoices", $record["_meta"]["id"]);

Example output

true

Emailing a signed document

Point attach_field at a signature field and the signer's certificate of completion is attached: the document exactly as it stood when they signed it, plus the full audit trail. attach_pattern is ignored, since there is only ever one certificate.

record_email_send("Main SMTP", [
    "to"      => $record["email"],
    "subject" => "Your signed agreement",
    "html"    => "<p>Thank you for signing. Your copy is attached.</p>",
    "attach_field" => "clientsig"
], "contracts", $record["_meta"]["id"]);

Two things worth knowing:

The certificate is generated at the moment you send, not stored and fetched. That means the copy the signer receives reports whether the document had been edited since signing, as at the moment it went out.
If the field has not been signed, this throws and nothing is sent. That is deliberate: an email saying "your signed agreement is attached" with nothing attached is a much quieter failure. Trigger on the signature field changing, and check the status first if the flow can run on unsigned records.

Notes

Replies thread back onto the record as email_in comments.
Send failures are logged to the run log (status "E") and the comment is marked dropped. They do not throw.
Pair with pdf_generate() to generate and email a document.