ADR-071: Email delivery reports observed outcomes¶
Status¶
Accepted 2026-10-29. Specializes ADR-051 for the CTF email channel (ADR-051-R14) and amends PLAT-103. Issue #1525 records the work. The design records the architecture, the data flows, and the security controls.
Context¶
CTF announcement state advanced before recipient outcomes were known. Workspace invitations used a fire-and-forget thread pool, so a restart lost the send. Administrator password reset reported success when the send failed. A console backend printed signed links to logs. The issue review (#2080) forbids a second email outbox. It requires retries, idempotence, and observable failure for each claimed critical delivery.
Decision¶
- CTF email uses the communication ledger. Email is a
ChannelAdapter. TheDeliveryAttemptrow is the durable command. The existing worker owns retry, backoff, and the attempt and elapsed ceilings. It checks the ceilings before I/O as well as after a result. - The occurrence delivery state is persisted.
CommunicationIntentstoresdelivery_stateseparately from its release lifecycle. One locked derivation from committed rows writes it. - Invitation and reset messages use one bounded synchronous attempt after
commit. The invitation stores its delivery status for the current
generation. The reset API returns
reset_delivery_failedwhen the backend does not accept the message. Resend is the retry. No second outbox exists. shared.email.attempt_email()is the only transport seam. It makes one backend call within one wall-clock deadline. Each blocking read and write of the connection gets only the time left. It returns a closed outcome, a closed reason, and an optional validated receipt. SDK retries and django-ses automatic throttling are off.- Non-delivering backends are unavailable outside development and test.
A console, file, or dummy backend sends nothing in a deployed runtime. The
outcome is
unavailable, never accepted. - Idempotency is at the ledger level. One command exists for each recipient and channel. Each attempt carries a stable Message-ID from the command key. A crash after provider acceptance and before settlement can send a duplicate. This at-least-once window is a documented limit.
Consequences¶
- Provider acceptance is the strongest success claim. It is not mailbox delivery, read, or acknowledgement.
- An HTTP request that sends an invitation or reset waits up to the interactive timeout.
- Deployments that render a console backend report email as unavailable.
- Organizer-only alerts stay unavailable. The participant ledger has no organizer recipient contract (ADR-065).