Email — Provisioning & Sending

Sending domain synthesis

A tenant’s sending domain is composed at read/send time, never persisted:

sendingDomain = "{sendingDomainSlug}.{mailZoneName}"
              = "acme.dev.ardamails.com"     # e.g. dev partition

mailZoneName is the partition mail sub-zone FQDN, read from the …-API-PartitionMailZoneName CloudFormation export at deploy time (e.g. dev.ardamails.com) — it is parametric, never a hard-coded apex. Because the domain carries the {partition} segment, the per-tenant DKIM and Return-Path records land inside the partition’s Route 53 zone, and DKIM aligns with the From domain under DMARC. A single synthesizer feeds both the send path (the From address) and provisioning (the Sender Signature address), so the verified domain and the actual send domain cannot drift. See Runtime → Partition Mail Topology for the export and zone topology.

The Postmark Server name is derived from the same sending domain — labels reversed, TLD dropped, joined with - (e.g. acme.dev.ardamails.com → ardamails-dev-acme). Embedding the partition keeps the name unique across partitions that share a Postmark account (dev + stage share PostmarkNonProd; demo + prod share PostmarkProd), avoiding cross-partition DuplicateName collisions.

Provisioning — the 4-step sequence

TenantProvisioner runs four steps in order, so every Postmark call precedes the DNS write (a Postmark failure leaves nothing in Route 53 to clean up):

1. createServer — create the per-tenant Postmark Server; encrypt its token immediately (the plaintext is never stored or logged).
2. createSignature — create one Sender Signature for the fixed From address; obtain the DKIM and Return-Path record values to publish.
3. installWebhook — install the event-delivery webhook on the Server (using the per-tenant Server token, not the account token).
4. writeRecords — write the DKIM TXT and Return-Path CNAME into the partition zone via a short-lived STS-assumed Route 53 role.

The published records are exactly what Postmark returns: the DKIM host (<selector>._domainkey.{slug}.{partition}.ardamails.com) and the Return-Path host (pm-bounces.{slug}.{partition}.ardamails.com) — never hand-built names. DKIM TXT values are chunked to ≤255-octet strings so 2048-bit keys publish.

On any step failure the completed prior steps are compensated (deleteSignature → deleteServer; 404 = success). Decommission reverses the sequence; re-provision cleans partial state first.

Send pipeline

EmailSendService.send runs outside any transaction, behind an idempotency bracket (claim-or-replay, then settle), with three gates before the Postmark call:

1. Malformed-input gate → 400 when neither body is present or attachments exceed the size cap.
2. Suppression gate → 403 when the recipient has a live suppression.
3. canSend gate → 404 (missing config) / 412 (not sendable).

On a fresh attempt the service builds the request — From fixed to {configuration.signature.fromLocalPart}@{sendingDomain}, no caller override — calls Postmark, and persists a Sent or Failed EmailJob atomically with the idempotency settlement. A transient terminal failure releases the idempotency claim so a same-key retry is a fresh attempt rather than a permanently-replayed error; a definitive rejection records a Failed row.

SPF / DMARC

SPF and DMARC live at the partition apex ({partition}.ardamails.com, provisioned by infrastructure) — not per-tenant. Per-tenant mail authenticates via DKIM alignment under DMARC relaxed alignment; the envelope-from is Postmark’s Return-Path subdomain. The module’s writeRecords publishes only DKIM + Return-Path — no per-tenant SPF or DMARC.