Email Module — Design Decisions

Author: Miguel Pinilla Date: 2026-06-18 Status: Accepted

Three decisions resolved during the Email module’s pre-go-live design reconciliation (the email-path-resolution investigation). They were decided together because they all bear on how a tenant’s sending identity is composed and verified.

D1 — Partition-qualified sending domain from the published zone-name export

Context. A tenant’s sending domain must carry the deployment partition ({slug}.{partition}.ardamails.com) so that per-tenant DKIM / Return-Path records land inside the partition’s Route 53 zone and DKIM aligns with the From domain. An early implementation built a flat {slug}.ardamails.com with a hard-coded apex and no partition — records would have been rejected by Route 53’s zone-containment rule and DKIM would not align.

Decision. Compose the sending domain as {slug}.{mailZoneName}, where mailZoneName is read from the partition’s …-API-PartitionMailZoneName CloudFormation export at deploy time. The mail-root is never hard-coded in the operations component. A single synthesizer feeds both the send path and provisioning, and the Postmark Server name is derived from the same domain (ardamails-{partition}-{slug}).

Consequences. The synthesized domain is guaranteed equal to the zone the records are written into (the export is that zone’s name), so the partition segment cannot drift from the records’ home. Server names are unique across partitions sharing a Postmark account. No new “partition” representation is introduced — the module reuses the export it already consumes for the zone id.

D2 — Fixed From address (no per-send override)

Context. A Postmark Sender Signature authorizes exactly one From address. The module had carried a per-send fromLocalPart override (a leftover from a Postmark-Domains model that authorizes any address on a domain), which a Signature cannot honor — a send from an unsigned local-part would be rejected by Postmark.

Decision. The From address is fixed by the configuration’s signature ({signature.fromLocalPart}@{sendingDomain}, default noreply@…). The per-send override is removed end-to-end (API, domain, persistence). The multi-From capability (migrating to the Postmark Domains API) is deferred to PDEV-903.

Consequences. Sends are always from a verified address. Callers lose per-send From flexibility until PDEV-903; this is acceptable for v1 transactional mail.

D3 — Drop SPF verification from the activation gate

Context. The verification gate required Postmark’s SPFVerified flag, but Postmark has deprecated SPF verification, and the module publishes no per-tenant SPF record (SPF lives at the partition apex). Requiring SPFVerified risked a configuration that never reaches OK.

Decision. The gate is DKIMVerified ∧ ReturnPathDomainVerified. SPF verification is dropped (the dead SPFVerified field is removed); Confirmed is not required either (an automated noreply@ address has no mailbox to confirm). Apex SPF/DMARC records are kept — only the verification check is dropped.

Consequences. Per-tenant mail authenticates via DKIM alignment under DMARC relaxed alignment; apex SPF still covers the envelope path. No schema change (the flag was transient).

References

Email — Provisioning & Sending
Runtime — Partition Mail Topology
Parametric Infrastructure Values — the reusable guideline distilled from D1.