System Email

System Email is a partition-level, system-originated (administrative) email capability. Any Module or Component in the platform acquires it through configuration and a library call — the same way a component acquires database access — rather than by calling another module’s endpoints. It is distinct from the Shop Access — Email module, which is a tenant-provisioned capability tenants use to send from their own sending domain.

The capability’s first intended consumer is the invitation workflow (Invite User to Tenant), which today still ends with a user manually copying an invitation link into their own mail client. Adopting the capability there is a follow-up project, not part of what is described on this page — System Email is not invitation-specific, and any other component with a reason to send administrative mail can adopt it the same way.

Position in the functional viewpoint

Aspect	Value
Domain	system
Module	messaging
Service	system-email
Endpoints	None for now — in-process capability only (see What’s delivered below)

What’s delivered

The capability ships in two repositories, plus the runtime plumbing that connects them:

1. A per-partition SystemEmailServer, provisioned by the infrastructure repo at partition create/update. Every active partition (dev, stage, demo, prod) gets one dedicated Postmark Server (SystemEmailServer-{fqn}) whose token is generated at provisioning time, custodied in the partition’s 1Password vault, and delivered to runtime through the platform’s standard δ.1 secret-delivery flow: 1Password → amm.sh → CloudFormation NoEcho parameter → AWS Secrets Manager → External Secrets Operator (ESO). The token is never stored in a database.
2. A server-identity-agnostic sending library, cards.arda.common.lib.infra.email, in common-module. It defines EmailSender, the EmailMessage/SendEmailOutcome types, EmailServer (the connection value every construction path produces), EmailSenderFactory, SendRetryPolicy, and the optional email {} HOCON configuration block bound by ConfigurationProvider.emailConfiguration. The library carries no knowledge of which server it is talking to — see Integration guide for how a component acquires a sender.
3. No REST surface. The capability is consumed in-process only, by design (design decision DQ-006) — there is no /v1/… endpoint for system email, and none is planned for this capability itself. Diagnostic/administrative tooling for system mail is deferred to a future System Administration console (PDEV-1250).

A minimal as-built view of how these pieces connect:

Key design facts

• Kill switch by absence. No email {} configuration block means the capability is off — the component boots normally and no sender is constructed. A present-but-malformed block fails component boot loudly, the same posture as the platform’s other required configuration bindings.
• No hard-coded server identity in the library. EmailSenderFactory builds an EmailSender from an EmailServer connection value; callers produce that value either from the component-level email {} block (the system path) or from their own runtime configuration store — the tenant-scoped Shop Access — Email module uses the same factory from its database-backed EmailConfiguration rows.
• Sends carry retry. Transient failures (HTTP 429, network/5xx) are retried inside the library per SendRetryPolicy (3 attempts, exponential backoff from 500 ms, capped at 10 s); rejections (4xx) are never retried.
• Outcomes are classified, not just enumerated. SendEmailOutcome groups its leaves under Success / Transient / Permanent sealed interfaces, so callers match on the group rather than re-deriving retryable-vs-terminal at each call site.
• No new DNS or Sender Signature. System mail sends from system.{partition}.ardamails.com, riding the partition’s existing Sender Signature — no new DNS records were added for this capability.
• Provisioning is idempotent. Re-running a partition deploy converges without creating a duplicate Postmark server or vault item.

Using the capability

See the Integration guide for the concrete steps a component follows to configure, wire, and use the capability — including the exact HOCON block, the composition-root wiring pattern, and the Helm secret-delivery gate.

Rationale, decisions, and diagrams

The full design — structural and behavioral diagrams, all seven decision questions with rejected alternatives, operational controls, and the provisioning/runtime sequence diagrams — lives in the roadmap design rather than being duplicated here:

• Design: Invitation Mail Server — the design document (the project is named for its originating use case; the delivered capability is general-purpose, as described on this page).
• Decision Log — the seven settled decisions (sender signature, token custody, CDK placement, library sourcing, sender acquisition, operations wiring scope, webhook posture).
• Secret Delivery Pattern — the δ.1 flow this capability’s token delivery follows.

Linear

• PDEV-1235 — Invitation Mail Server