Send transactional mail through Resend, not SES

[jodeleeuw]

AWS denied the SES production-access request. That would have left every send restricted to verified recipient addresses — failing for every real researcher, and failing terminally, since mail-delivery.ts classifies a rejected recipient as permanent and does not retry it. Resend has no equivalent gate, so the transport moves there.

Only the transport moved

mail.ts's document contract, the claim/lease machinery, the delivery.* outcome fields, the Firestore TTL policy and purge-user-data.ts's owner query are all untouched. That's what kept this to one file plus its tests — the same property that made the earlier extension→SES swap cheap.

• buildSendEmailInput emits Resend's JSON body, using reply_to, not replyTo. The Node SDK takes camelCase; the raw REST API takes snake_case and ignores unknown keys silently — so getting this wrong means every notification goes out with no Reply-To and nothing says so. Pinned by its own test.
• classifySesError → classifyMailError, rebuilt on Resend's documented error codes with HTTP status as the fallback.
• No SDK. One fetch to one endpoint. @aws-sdk/client-sesv2 is gone, and with it the dynamic import that existed to keep the SDK off apidata's cold-start path.
• Undici unwrapping. Node's fetch reports every network failure as TypeError: fetch failed with the real diagnosis on .cause, so errorName unwraps it. Without that, a momentary DNS blip classifies as unrecognised → terminal → a silently lost notification. Tested in the wrapped form, since that's the only form the code ever receives.

One behavioural change, deliberate

Ambiguous failures (timeouts, ECONNRESET) are now retryable. They were terminal because SESv2 has no idempotency token: a request that went out and never answered couldn't be retried without risking a second copy of a notification whose entire value is arriving once, so the old code chose to lose the mail.

Resend takes an Idempotency-Key, and we send the mail document's id on every attempt — so the retry is a no-op at Resend rather than a second send. We get the retry and exactly-once instead of choosing.

The key expires after 24h. Every retry path here is minutes wide, but that bounds any future retry mechanism, and it's called out in AMBIGUOUS_ERRORS and in both test suites so a later change can't quietly invalidate it.

Config

Six *_SES_* repo secrets become one *_RESEND_API_KEY per environment.

The test site is now expected to send, reversing this runbook's earlier "leave it unset" default. Reason: the test site is the only place delivery is exercised before production — the emulator short-circuits before sending, and the unit suites mock the transport at a function seam. Reputation and daily quota are shared with prod, which is documented in runbook §2(d) along with what to actually smoke-test.

Also corrects three things found while verifying the deploy steps

None caused by this change:

• The production project is osf-relay, not datapipe-prod — .firebaserc's default, and what firebase use default selects. GCP project ids are immutable, so datapipe-prod never existed. The runbook and three migration scripts all had it wrong, including the backfill's FIREBASE_PROJECT_ID || 'datapipe-prod' default.
• Runbook §4's console instructions named delivery.endTime where the gcloud command says delivery.expireAt. Following the console path creates a policy that reaps every mail document the moment it's delivered — no debugging window, and nothing saying it happened.
• mail.ts's header still described the extension as the transport and claimed switching providers was a config change rather than a redeploy. Now also explains why the collection exists at all (the tx.create inside the episode transaction) and why the TTL does.

Testing

Full suite green on the rebased tree: 79 suites, 1119 tests, plus tsc and lint.

The two mail suites were rewritten rather than patched — 48 pure tests (request mapping, error taxonomy, claim state machine, config) and 19 emulator-backed ones. No test in the repo can reach api.resend.com: the transport is injected at a function seam, so the real one is never constructed.

Deploy prerequisites — status

• jspsych.org verified in Resend
• PROD_RESEND_API_KEY / TEST_RESEND_API_KEY set
• mail TTL policy on datapipe-test — delivery.expireAt, state ACTIVE
• mail TTL policy on osf-relay — still absent, needed before prod
• Post-deploy smoke test: change a contact email on a test account, confirm the mail document reaches delivery.state: "SUCCESS" with delivery.info.transport: "resend"

Known gap, not addressed here

Hitting the daily quota leaves the mail document as a retryable ERROR that nothing retries on a timer — and upload-failure-notify.ts sets notifiedAt in the same transaction that enqueues, so the episode is already armed as "told them." The researcher is never notified and the system believes it did. Closing that needs a scheduled sweeper, which is separable from this change and has its own design question (it must be kind-aware, and it collides with the 24h idempotency window).

🤖 Generated with Claude Code