Email reference

The surface. Using Email is the same ground with the code you write around it.

Config options

OptionDefaultMeaning
fromAddressnoreply@example.comThe sender of every message enqueue writes. Must use a domain onboarded onto Email Service
fromNamePithyWhat recipients see. A recognizable name improves deliverability. Also the name a per-message sender with none falls back to
baseUrlPUBLIC_ORIGINWhat tracking and unsubscribe links are built against
basePath/emailWhere the management routes mount. Does not affect the recipient callbacks
themesaffronOne of four, or fine-tuned with a custom theme object
schedulerEnabledtrueWhether the every-minute scheduler runs
devDeliveryremoteUnder pithy dev: remote sends real mail; simulator logs and writes to disk

The recipient callbacks keep a fixed prefix and are unaffected by the base path, because those URLs are already minted into mail nobody can recall.

A per-message sender takes enqueueAs. email().enqueueAs(addresses) returns an enqueue that accepts from: { address, name? } for those addresses; plain enqueue refuses any from with email/invalid_payload. A send Email Service refuses because the sender’s domain is not onboarded or not verified fails the job with the domain named, and no other sender is tried. Sending as another address has the call.

Templates

Kit copy, translated with the kit: magicLink · otp · welcome · securityAlert · invite · passwordChanged · accountSuspended · accountReinstated · deletionScheduled · deletionComplete · organizationMemberAdded · organizationMemberRemoved · organizationOwnershipTransferred · organizationSuspended · organizationReinstated · organizationDeletionScheduled · leadCapture

The four account-lifecycle templates are sent by auth, on a suspension, a reinstatement, a deletion and a completed purge. Each can be turned off in auth’s lifecycleEmails. Suspended and deleted accounts has what each says.

The six organization templates are sent by organization. Three go to a member, when an operator adds somebody to an account, removes them, or forces ownership onto them through the control plane. A previous owner removed by a forced transfer is told they were removed, and the operator’s reason is never in that mail. Each can be turned off in organization’s operatorEmails. The other three go to the account’s owners, when an operator suspends, reinstates or deletes the account itself: organizationSuspended carries the reason and any end, and organizationDeletionScheduled the date the data is erased. Each can be turned off in organization’s lifecycleEmails. Organization lifecycle has who they reach.

Payload-carrying, only as localized as your own copy: testerNudge · supportReply · operationalNotice · newsletter · marketingCampaign

The registry is closed. A template is a kit artifact rather than something you add — which is what lets the send Worker carry every one of them in its own bundle in every language.

Job statuses

StatusInputs keptWhy
sentDroppedThe one status a retry is already refused for — retrying a delivered job is a duplicate email to a real person
failedKeptThe retry route exists for exactly this row, and re-renders from the payload
suppressed, bouncedKeptNothing was delivered. A manual block can be lifted
pending, scheduled, sendingKeptThe send has not happened yet
undispatchedKeptNot until a host Worker exists to claim it

undispatched is a truthful status, never a grave. The day the host is deployed, its first tick claims those rows.

Suppression

EventEffect
hard_bounceBlock
complaintBlock
manualBlock
unsubscribeBlocks marketing, not sign-in

One suppression database per project, not per environment: an unsubscribe in production has to stop staging too.

Management routes

Every one is control-plane and default-denied. With the seam uncomposed, all seven answer 403.

MethodPathScope
GET/email/jobsemail:jobs:read
GET/email/jobs/:idemail:jobs:read
POST/email/jobs/:id/retryemail:jobs:retry
GET/email/suppressionsemail:suppressions:read
POST/email/suppressions/lookupemail:suppressions:read
POST/email/suppressionsemail:suppressions:write
POST/email/suppressions/removeemail:suppressions:delete

The two lists narrow on the server. GET /email/jobs takes status, template (one template id, exactly, such as magicLink) and category (transactional or marketing), together or apart, and pages on the same cursor. Migration 0002_job_filters adds the indexes that serve them. GET /email/suppressions takes reason, and active: true for the blocks in force now, false for the ones whose expiry has passed. A value outside those is refused as validation/invalid_input, not ignored.

One address is looked up in a body, never a URL. POST /email/suppressions/lookup takes { "email": "<address>" }, matched exactly against the stored key, and answers the listing’s own shape, { suppressions, nextCursor }, with the one matching row or none, so it answers whether one person is blocked without disclosing anybody else. A query string is written to every request log between the client and the Worker, so the listing’s query is strict: ?email=, or any key it does not name, is validation/invalid_input (400), never the whole list as though it matched. The lookup is audited as email/suppressions_read with lookup: true, and the address stays out of the trail.

Every call is audited, reads included. A block is silent to everyone it affects, so the trail is the only record it happened.

Recipient callbacks

Three, at a fixed prefix, sealed, and public because the token is the credential: click, open, unsubscribe.

MethodPathWhat it does
GET/_pithy/email/c/:tokenRecords a click, then redirects to the destination sealed in the token
GET/_pithy/email/o/:tokenRecords an open; answers a 1×1 PNG
GET/_pithy/email/u/:tokenRecords nothing. A page whose one button posts back
POST/_pithy/email/u/:tokenUnsubscribes. The page’s button and a one-click header both land here

A token is 3.<kid>.<sealed>: the key version, then AES-256-GCM ciphertext under a key derived with HKDF-SHA256 from that version of email-link-signing-key. Nothing in it decodes to a claim, the recipient and a click’s destination included, so a request log that records a link names nobody. The signed <payload>.<signature> format before it is read and never minted, until its own exp.

The unsubscribe POST takes an optional form body: List-Unsubscribe=One-Click, and a reason, of which the first 200 characters are stored. A malformed or repeated field reads as absent or as its first value, so no body can block the opt-out. No callback reads a query string, and a ?reason= is ignored.

Every token carries its key version, and is checked against every version the key still holds — so a link in a months-old email still verifies after a rotation that kept the previous version.

Bindings

BindingTypeWritten by
DBd1pithy add
EMAIL_SUPPRESSIONSd1pithy add — the project-wide list
EMAIL_SENDERworkflowpithy add, naming the host across scripts

The Workflow entry is complete before the host exists, so local dev binds it either way.

Secrets

email-link-signing-key — minted, arbitrary, and rotatable, with an overlap of 90 days: a rotation by the secrets manager keeps the previous key for as long as a link lives, so links already in inboxes keep verifying. It declares no period of its own. pithy secrets rotate keeps no previous key, so a link already sent stops verifying when it lands. A host that raises the link lifetime past 90 days wants a longer overlap, declared in the project’s own registry.

Provisioning

All of it is pithy email provision.

pithy email provision creates the shared suppression database, migrates it, and deploys the per-environment host.

The three routing flags are all or nothing. Enabling Email Routing on a zone points its MX at Cloudflare — so use a subdomain, never your apex.

Peer capabilities

Required: secrets.

Composed with i18n, the shell follows each job’s recorded locale.

Composed with payments, an enqueue that names its billing subject is charged against the emails meter. Where that meter is enforced, an enqueue past the period’s quota is payments/quota_exceeded (402) and writes no job; an enqueue naming no subject is never counted. Counting mail against a plan has the call.

Composed with consent, email’s two purposes, email.marketing and email.tracking, are asked before every enqueue that names a consentSubject. A marketing message the subject has not agreed to is born suppressed with consentWithheld on the result and a consent:email.marketing event, and tracking runs only with email.tracking. A withdrawal from marketing writes a permanent unsubscribe suppression; a stronger one, a hard bounce, a complaint or a manual block, is never downgraded, and a re-grant lifts only the withdrawal’s own. Using Email has the call.

What is not here

No segment builder, no A/B testing, no drip editor. There are campaign templates and a suppression list, and that is the extent of the marketing surface.

No inbox. Inbound mail is handled for bounces and complaints; reading and answering customer mail is support.

No deliverability guarantee. SPF, DKIM, DMARC and reputation decide that, and what you can do about each is a page of its own.

ESC