Build Transactional Email Deliverability Core on nextjs-postgres-resend

A fresh sending domain lands in spam by default — and the specific bugs that keep it there (deduping bounce webhooks on the wrong field, letting a later bounce silently downgrade a complaint, blasting a brand-new domain past its trust ramp, escalating DMARC on a root domain that has other senders) are exactly the kind of thing a bare coding agent gets wrong quietly, not loudly. This pack builds the full transactional email core for a Next.js + Postgres app — suppression list, warmup governor, Svix-verified webhooks, staged DMARC rollout with a DNS checker, two templates with mandatory plain-text parts — against Resend, with the acceptance tests already written. The receipt is real: **3 of 3 clean-room builds passed on `claude-sonnet-5`, all 10 acceptance checks green in every run, ~10 minutes mean build wall time.**

Example use cases

• **An indie SaaS founder launching on a brand-new domain** — password resets and receipts need to land in the inbox from day one, without manually researching DMARC staging or bounce-webhook idempotency first.
• **A dev agency re-stamping the same email core across client Next.js apps** — ship the identical suppression/warmup/webhook machinery into five different client projects instead of re-solving deliverability per contract.
• **An existing business adding transactional app mail without risking its root domain** — Google Workspace or another mailbox already sends as `@yourdomain.com`; the dedicated mail-subdomain design (and Path B of the go-live checklist) stages DMARC on `mail.yourdomain.com` without ever touching the root record other senders depend on.
• **A team that wants to keep the option of leaving Resend** — the suppression list and email event log live in the team's own Postgres, not locked inside a provider dashboard, so a future move to Postmark or SES is writing one class, not rebuilding suppression history from scratch.

Scale envelope

Derived from the shipped architecture and Resend's own published pricing (checked August 2026 — reconfirm current tiers at resend.com/pricing, since they change), not aspiration. Numbers below are labeled as estimates where they are estimates; nothing here is load-tested by the receipt.

• **The warmup governor is the pack's own pacing ceiling for the first 45 days**, and it is deliberate, not incidental: 20/day (days 1–3) → 50 (4–7) → 100 (8–10) → 200 (11–14) → 400 (15–18) → 800 (19–22) → 1,600 (23–26) → 3,200 (27–30) → 6,400 (31–37) → 12,800 (38–44) → unlimited (day 45+). This is a reputation-safety policy ceiling, not a technical one — it can't be safely skipped on a fresh domain (see `GO-LIVE-CHECKLIST.md`).
• **Resend's free tier** (3,000 emails/month, capped at 100/day, one custom domain) lines up almost exactly with the governor's own day-8–10 stage (100/day) — the free plan and the pack's built-in caution agree on what's safe through roughly the first week and a half. Sustained at that 100/day cap for a full month is also 3,000 emails — the free plan's own monthly ceiling — so a fresh domain typically outgrows free-tier before the ramp reaches its day-11 stage (200/day) if it's actually using its full daily allowance; most domains send under their cap early on, so in practice free tier often lasts a bit longer. **Estimate, not measured.**
• **Resend Pro** ($20/mo, 50,000 emails/month, ≈1,667/day sustained) covers sustained-at-cap sending through roughly day 23–26, where the ramp's 1,600/day stage crosses Pro's daily average. The higher stages (3,200–12,800/day, days 27–44) are headroom the ramp *permits*, not volume you must send — the ramp is a ceiling, not a target; if your real volume grows past ~1,600/day sustained, size the Resend plan to your volume, not to the ramp. **Estimate.**
• **User-count reasoning** (back-of-envelope, not receipt-measured): at a typical transactional cadence of roughly 1–3 emails per user per month (welcome + occasional password reset + receipts), the free tier's 3,000/month ceiling covers on the order of **1,000–3,000 active users**; Resend Pro's 50,000/month covers roughly **15,000–50,000 active users** at that same cadence.
• **Rows/storage:** the schema is two tables — `suppressions` (one row per address ever suppressed) and an append-only `email_events` log. Millions of rows in either is an ordinary Postgres table size for this schema; it isn't the constraint.
• **First ceiling:** the warmup governor's own ramp for the first 45 days on any fresh domain — a policy ceiling you should not route around. After day 45, the real ceiling becomes whichever Resend plan tier you're on.
• **Upgrade path:** upgrading Resend's plan tier is a dashboard/billing change only — same `RESEND_API_KEY`, zero code changes. Leaving Resend entirely means writing one new class against the `EmailProvider` interface (e.g. `PostmarkProvider`); the suppression list, warmup governor, and DMARC staging all live in your own Postgres and DNS, untouched by the switch.

**What this comfortably covers as shipped:** a single product on a single sending domain moving through its 45-day warmup on Resend's free-to-Pro tiers — solo founders, small SaaS teams, agencies standing up the same core per client. **What it isn't sized for out of the box:** multi-domain or multi-tenant sending at high volume on day one (the warmup ramp and single-domain scope are both deliberate, not oversights) — that's a larger Resend plan plus, if you need it, running the module per tenant domain, not a change this pack makes for you.

**What it costs to skip the pack (modelled, not measured):** building this core yourself the way most people actually work — one agent on a top-tier model, no cheap-tier routing, no parallel subagents, no prompt-caching discipline — models out at roughly **$45–180 in API tokens, likely around $90**. That's this pack's own measured build volume repriced at Opus-class rates, multiplied by an exploration factor for the deliverability decisions listed above; the pack-guided build itself measured ≈$3 of tokens per verification run (August 2026 rates), the cheapest in the catalog. Honest reading: against the $79 price that's essentially break-even, so don't buy this for the token savings. Buy it because the bug classes above are the silent kind, and the receipt says 3 of 3 clean-room builds passed all 10 checks.

What you get

Features:

• `sendEmail()` pipeline: suppression check → warmup cap → template render →

Resend send (idempotency-key passthrough) → event log, in that order

• Provider seam (`EmailProvider` interface) — swap Resend for Postmark/SES by

writing one class; a mock provider ships for tests and local dev

• Suppression list in your own Postgres with non-negotiable semantics

(complaints permanent and non-removable; soft bounces never suppressed)

• Svix-signature-verified webhook endpoint, idempotent on the delivery id,

auto-maintaining the suppression list from bounces and complaints

• 45-day warmup ramp table with UTC day accounting; over-cap sends deferred

with their full send input stored, and a `npm run drain` routine that

replays them in FIFO order within each day's remaining budget, marking

each row so it never double-sends — schedule it and nothing is ever dropped

• Staged DMARC rollout (none → quarantine → reject) with a checker CLI that

validates SPF, DKIM, return-path MX, and DMARC live or against fixtures

• Two production templates (welcome, password-reset) with mandatory

plain-text parts, establishing the template pattern

• Plain-SQL migration, append-only email event log for ops/debugging
• Full vitest acceptance suite on in-process Postgres (PGlite) — no Docker
• One-page human go-live checklist covering the only manual steps

Screens/pages:

• `/dev/emails` — template preview gallery (subject, HTML iframe, text part),

disabled in production

• `POST /api/webhooks/resend` — webhook endpoint (401 on bad signature)
• CLI: `npm run check-dns` — per-record PASS/FAIL report with detail text
• CLI: `npm run drain` — replays warmup-deferred sends within today's

remaining budget; prints a one-line replayed/remaining summary, exits 0

nextjs-postgres-resend versions lock