ADR 0001: A Postgres delivery ledger
Why every message is a row in one Postgres ledger instead of per-campaign Durable Objects.
Date: 2026-10-24. Status: accepted.
Context
Pneumail replaces several hosted email tools for Backpack and Front Door, at 250,000 sends a day. An earlier system, Campaign Studio, ran one Listmonk engine per client on a shared SES account. Its client rollout stopped because one bad list could suspend every client and bounce processing was not wired. Pneumail has to solve both from the start.
How the design was chosen
Two designs were sketched independently from the same brief, one by Claude Opus and one by GPT Sol, using the pstack architect method.
- Candidate A kept each campaign’s ledger in its own Durable Object and each publication’s contacts in another, with no central database.
- Candidate B kept a single Postgres delivery ledger, a rate governor Durable Object per SES account, and one SES tenant per workspace.
B became the base. Workspace-wide questions are one indexed query instead of a fan-out, throughput does not depend on one object staying fast, and approval, suppression and the send decision commit in one transaction.
From A we kept: SES message tags as the routing key for events, address-level suppression of NoEmail bounces
across workspaces, our own click tracking for bot filtering, configuration-set suppression off, and EventBridge as
the one event intake. A’s rule for retrying unknown sends from the event watermark was dropped after critique,
because EventBridge does not deliver in order.
Critique
The merged design went through the design critique loop in AGENTS.md. Round 1 found that the Feedback-ID format
was impossible on SES, that Gmail complaints never reach SES, that Hyperdrive’s default cache could send to an
unsubscribed address, that test sends skipped approval, and that the audience froze at schedule time instead of
send time. All of these are fixed in docs/explanation/architecture.md.
Consequences
Pneumail depends on PlanetScale Postgres through Hyperdrive, with caching off. A message is dropped, not retried, when SES times out.