A request never sends mail
const { jobId, status, subject } = await enqueue(env, {
template: "welcome",
to: user.email,
locale: user.locale,
payload: { name: user.name },
});It writes a row and returns. A Workflow delivers it, with retries and durable state that survive a Worker restart. Sending a transactional email is this call with the surrounding setup.
The request that asked returns in milliseconds and does not care whether the message has left.
Counting mail against a plan
Pass subject on the enqueue to say whose plan the message is sent on behalf of — the holder pair payments bills, such as { subjectType: "organization", subjectId: org.id }. It is not the subject line: that is the subject the result hands back.
Leave it out and nothing is counted, which is right for every message the kit sends on its own account: a magic link to somebody who has not signed up is nobody’s usage. Name it on mail a customer’s plan pays for, such as a notification their workspace triggers. A recipient on the suppression list is never counted either.
Where payments enforces its emails meter, an enqueue past the period’s quota throws payments/quota_exceeded (402) and writes no job. Left advisory, the field changes nothing. Tiers, quotas and features has the period and the meter.
Sending as another address
enqueue sends every message as fromAddress and fromName, and refuses a per-message from with email/invalid_payload, writing no row. A capability that answers from addresses of its own declares them once, at compose, with enqueueAs:
const enqueueReply = mail.enqueueAs(["support@help.example.com"]);
await enqueueReply(env, {
template: "supportReply",
to: customer.email,
from: { address: "support@help.example.com", name: "Jim Scott" },
payload: { /* … */ },
});The function it returns accepts from: { address, name? } for those addresses and refuses any other. Leave out name and fromName is used. The sender is stored on the job. This is how support replies from the inbox a customer wrote to.
It is a convention, not a security boundary. Any code in the Worker can call enqueueAs with any list. What limits sending is Cloudflare, which sends only from domains onboarded onto Email Service. A send refused because the domain is not onboarded or not verified fails the job with the domain named in error, and is never retried as another sender.
Three ways to schedule
Immediate. A pending row, and the Workflow starts now.
Scheduled. A row with an absolute time.
Per-recipient-local. Somebody’s local time-of-day in their own timezone, resolved to an absolute time — so 9am wherever they are is one row per recipient with different absolute times, rather than one job reasoning about zones while it runs.
An every-minute scheduler finds what is due and fans it into batches sized to the volume.
What the result carries, and the trap in it
The job id, the status, and the rendered subject.
That last one is there so a caller with an administrative trail does not have to re-render it — which would mean restating your theme and the layer stack, then pinning your copy against the kit’s to notice when its wording moves.
But it is the enqueue-time render. The send renders again at the moment the message leaves and rewrites the row from that — so a scheduled job whose catalog was retranslated in between delivers the new sentence while your recorded value keeps the old one.
And the gap is not only the wait in the queue: the send Workflow is its own deploy carrying its own copy, so a send Worker whose copy has drifted from the Worker that enqueued stands until the two are back in step. An immediate send lands inside that window like any other.
Record what you queued. A trail that must reflect delivery reads the row back afterwards.
The body is deliberately not in the result. It is large, it is the thing this capability is careful never to log, and it is rendered inside the Workflow at the moment it leaves.
Sending from your own Workflow
A route reaches the enqueue function through the composition hook, and should keep doing that — it is typed and explicit.
A Workflow class has no such route. The runtime constructs it with the environment and nothing else; the function is a closure rather than a binding, and Workflow parameters are serialized, so a closure cannot travel in one either.
The wrong fix is to rebuild the send identity inside the step, which puts your sending address in a second place free to drift from your config.
The right one is an environment-only entry point, which resolves the same composed identity from what the runtime did hand you.
Templates
Seventeen are the kit’s own copy and are translated with it: magic link, one-time code, welcome, security alert, invite, password changed, account suspended, account reinstated, deletion scheduled, deletion complete, organization member added, organization member removed, organization ownership transferred, organization suspended, organization reinstated, organization deletion scheduled, lead capture.
Five carry your words as payload: tester nudge, support reply, operational notice, newsletter, marketing campaign.
The shell follows the job’s locale; a payload-carrying template is only as localized as your own copy. Mail in the reader’s language is where that line falls in practice. Translate your summary yourself, through your own domain, before you enqueue — the kit cannot translate a sentence it has never seen.
Transactional versus marketing is decided by the template
A transactional message renders with no unsubscribe link and no unsubscribe header, whatever context it is sent in. A marketing template forces both.
The kind is declared by the template rather than passed at the call site — so there is no context that could add an unsubscribe footer to a sign-in message, and none that could take one off a campaign.
Tracking
Links in a tracked email are sealed callbacks on your own origin, at a fixed prefix — because those URLs are minted into mail nobody can recall, so they cannot move with your base path. Nothing in the URL decodes to the recipient, so a request log that records one learns nobody’s address.
A click records and redirects. An open loads a pixel. An unsubscribe link opens a page whose button records the opt-out, and a mail client’s one-click header records it directly. Your own flow passes a reason in the POST’s form body, never the URL. Tracking has the rules.
Every token carries its key version, so a link in a months-old email still verifies after a rotation.
Consent
Email declares two consent purposes, email.marketing and email.tracking. With consent composed, an enqueue asks before either. Pass whose consent the message is sent under:
const { jobId, status, consentWithheld } = await enqueue(env, {
template: "newsletter",
to: user.email,
consentSubject: { kind: "account", id: user.id },
});A marketing template to a subject not consenting to email.marketing is born suppressed, nothing is sent, and the result carries consentWithheld: "email.marketing". Opens and clicks are tracked only for a subject consenting to email.tracking. A message with no consentSubject is withheld if it is marketing and untracked either way, because nobody’s consent can be shown. Transactional mail is never gated.
A withdrawal from email.marketing suppresses the address for marketing, permanently, so it also holds mail already scheduled. Granting it again lifts that suppression and no other. A withdrawal from email.tracking stops tracking on mail already queued.
Without consent composed, email behaves as it always has, and pithy doctor says tracking runs with no consent record behind it.
Suppression is automatic, and the database is yours
| Event | What it does |
|---|---|
| Hard bounce | Block. The mailbox does not exist, and hammering dead addresses damages the sending domain for every other sender on it |
| Complaint | Block. Continuing after a spam report is how a domain gets blocked outright |
| Manual | Block. An operator’s deliberate act |
| Unsubscribe | Blocks marketing, not sign-in. An opt-out is a statement about mail somebody chose to receive. A sign-in link is not that |
That last row is the one worth understanding. Somebody who unsubscribes from your newsletter still needs to be able to log in.
The list is one per project rather than one per environment: an unsubscribe in production has to stop staging too.
A delivered job stops holding its inputs
Once a message is sent, its inputs are dropped — because sent is the one status a retry is already refused for. Retrying a delivered job is a duplicate email to a real person, so nothing can ever need those inputs again.
Everything else keeps them: a failed job is exactly what the retry route exists for and it re-renders from the payload; a suppressed or bounced one delivered nothing; a pending one has not happened yet.
Before the host exists
Mail enqueued before provisioning is delayed, not lost.
It sits in a truthful status — never a grave — and the day the host is deployed, its first tick claims those rows exactly as it claims any stranded one. A tick running at all is the host existing.
Reading the job log
Six control-plane routes — the reference names them — every one default-denied. There is no session surface here at all — a recipient’s only routes are the three callbacks.
Every call is audited, reads included. A block is silent to everyone it affects, so the trail is the only record it happened.