Email

Outbound and inbound email capability — per-tenant Postmark-server provisioning, transactional send, encrypted credential delivery via ESO, and inbound webhook ingestion for delivery / bounce / complaint events. One of three Shop Access (SAC) sub-areas (alongside Print and Scan) that bridge Arda to external systems and devices.

The Email module is the first operations module on the canonical functional-hierarchy shape: it serves its configuration through the DataAuthority framework, mounts at /v1/shop-access/email/{configuration, job, job/postmark-events}, and derives its identity from the HOCON path modules.v1.shop-access.email. It is a module inside the operations component — it consumes the partition’s mail infrastructure (Route 53 sub-zone, Postmark account token, encryption key) through CloudFormation exports rather than owning any of it.

What it does

A tenant provisions an EmailConfiguration, which gives that tenant the right to send transactional email from a per-tenant sending domain. Provisioning creates a dedicated Postmark Server and Sender Signature and publishes the tenant’s DKIM and Return-Path DNS records into the partition mail zone; once Postmark verifies those records, the configuration becomes sendable. Callers then submit send requests, which are gated, sent through Postmark, and recorded as EmailJob rows; Postmark delivery webhooks project delivery status back onto each job and drive recipient suppression.

Key design facts

• Sending domain is {sendingDomainSlug}.{partition}.ardamails.com — the partition segment is mandatory and is sourced from the partition’s …-API-PartitionMailZoneName CloudFormation export (never a hard-coded apex). See Provisioning & sending.
• From address is fixed by the configuration’s signature ({fromLocalPart}@{sendingDomain}, default noreply@…). There is no per-send From override — a Postmark Sender Signature authorizes exactly one address. (Multi-From via Postmark Domains is deferred to PDEV-903.)
• Per-tenant isolation: each configuration gets its own Postmark Server + Sender Signature, so DKIM-domain reputation is isolated per tenant.
• Verification gate is DKIMVerified ∧ ReturnPathDomainVerified (Postmark’s SPF verification is deprecated and not used).
• Cross-Universe rule: tenant and user references are soft (no cross-service foreign keys or shared transactions).

Sub-pages

• Domain model — EmailConfiguration, EmailJob, SuppressionEntry, EmailEvent.
• Lifecycle — the operational (PENDING → … → OK / DEGRADED / FAILURE) and administrative (UNLOCKED / LOCKED / LOCKING) state machines.
• Provisioning & sending — the 4-step provisioning sequence, sending-domain synthesis, and the gated, idempotent send pipeline.
• Webhook ingestion — Postmark events, status projection, and suppression.
• API reference — the configuration, job, and webhook REST contract.

Runtime & operations

The Email module’s behavior is documented here; its substrate and operation live in their canonical layers:

• Partition mail infrastructure (zones, NS-delegation, IAM, the CFN exports the module consumes) — Runtime → Partition Mail Topology.
• Operating the running module (drift assertions, lock/unlock, verification troubleshooting, suppression management) — OAM → Postmark Service → Module Operator Runbook.
• Postmark account topology & credentials — OAM → Postmark Service.

Linear

• Initiative: Product / Shop Access / Email