Who this is for. Anyone sending email from a job. Afterwards you can tell, from the records, whether a message was queued, sent, delivered or refused, and you know which messages a job should not send at all.
The records a send is made of
| Record | Holds |
|---|---|
| Batch | One send: subject, from, reply-to, the template, a send-at time and a priority. A batch made by a job has its origin set to Hooks |
| Template | The body, already rendered by the job |
| One message, with its status, the provider's message id and any error | |
| Recipient | One address on the email: to, cc or bcc, a plain address or a person |
| Attachment | A file attached to the batch. The platform uses them for its own exports; a job cannot add one (Attachments) |
| Interaction | An open, a click (with its URL) or an unsubscribe reported back by the provider |
From the action to the inbox
- The Send Email action renders the subject, the addresses and the body with the site's engine. An address that is not an address,
Name <address>or a person id fails the action. - It creates the batch, its template and one email carrying every recipient, and queues the email. The action succeeds here, with the output Mail queued and the mailer batch id. Nothing has been sent yet.
- A worker picks the email up and fills the mailer's placeholders (below).
- The mail provider, SendGrid unless the platform has been configured otherwise, accepts it: the email's status goes from
queuedtosent. If the provider refuses it, the status isfailedwith the provider's error. There is no automatic retry. - With the provider's event webhook pointed at the site, later reports move the status to
deliveredorbouncedand record opens and clicks (Tracking).
So a run log showing Send Email as a success proves the message was queued, not that it arrived. The mailer's own records answer the second question; through the API they are GET /cdna-api/mailer/batches and GET /cdna-api/mailer/emails/{batch id}, which give each email's status, error, opens and clicks (Mailer API reference).
The mailer's placeholders
As it sends, the worker replaces %word% placeholders in the subject and body. When one of the To recipients is a person rather than a plain address, the first such person supplies %firstName%, %middleName%, %lastName%, %toName% and %email%; every email has %hostname% and %showInBrowserUrl%, a web view of the message at an address nobody can guess. Any other %word% becomes empty text, so a body that needs a literal word between two percent signs has to be written differently. The job's own variables are the better tool; the placeholders matter most for the platform's own emails, such as the password reset.
The body is sent as HTML when it contains a <body tag, and as plain text otherwise, one or the other: an HTML message has no plain-text alternative.
Transactional and bulk email
The two carry different obligations, and the difference is legal before it is technical.
| Transactional | Bulk (marketing) | |
|---|---|---|
| What it is | A message the recipient's own action caused and needs: a receipt, a password reset, a certificate, a booking confirmation | A message sent to a list: a newsletter, a promotion, a campaign |
| Consent | Not needed for the message itself, as long as it carries no promotion | Needed, and recorded, before the first send |
| Unsubscribe | Not expected | Required, working, and honoured on the next send |
| Sender identity | Your domain, authenticated | The same, plus the sender's identity and a postal address in the message |
| Where to send it from | A job | A marketing platform, fed with the list by an integration |
The laws that set these rules (the Spam Act in Australia, CAN-SPAM in the United States, GDPR and the ePrivacy rules in Europe and the UK) differ in detail, and the client's own advice decides the detail. What does not differ is the line: a receipt that grows a "you might also like" block has become commercial email and takes on the bulk rules.
Why bulk does not belong in a job. A job that loops over a list of people and mails each has no consent check, no unsubscribe handling and no per-recipient throttling: send it from a marketing platform instead, where consent, unsubscribes and throttling are built in. Treating a job's mail as transactional does not make it so; it is a compliance matter.
Writing the body
Email HTML, the theme partials that do not survive a mail client, and three complete emails are on Three worked emails.
Attachments
A job sends a link to a generated file rather than an attachment: Attachments, or a link.
Deliverability, tracking and testing
The sending domain, opens and clicks, and testing without mailing a customer: Deliverability, tracking and safe testing.
The password reset email is the third of the worked emails.