Mail Worker Migration

Mail Worker Migration

This runbook covers migration from:

• workers/cosmos/mail

to:

• workers/bookmarks/mail

for auth verification/reset and other Bookmarks email delivery.

Difficulty and timeline

• Estimated difficulty: medium (6/10)
• Recommended timeline: 3-5 days including staging burn-in

Success criteria

• Verification and reset emails send successfully.
• No regression in auth flows that depend on email.
• Fast rollback by restoring MAIL_SERVICE binding on auth worker.

Phase 1: Provision dedicated resources

Create Bookmarks-specific Cloudflare resources:

• KV namespace for mail state
• D1 database for mail metadata
• queue + DLQ
• secrets store entries (TURNSTILE_API_KEY, RESEND_API_KEY)

Update placeholders in:

• workers/bookmarks/mail/wrangler.toml

Phase 2: Deploy bookmarks-mail-worker

1. Deploy staging:
   • yarn workspace bookmarks-mail-worker deploy --env staging
2. Verify staging endpoints and send-email path.
3. Deploy production:
   • yarn workspace bookmarks-mail-worker deploy

Phase 3: Wire auth worker mail binding

Update auth worker service binding:

• MAIL_SERVICE -> bookmarks-mail-worker (prod)
• MAIL_SERVICE -> bookmarks-mail-worker-staging (staging)

Then deploy auth worker.

Phase 4: Validation

Run these checks:

1. Register user -> verification email is sent.
2. Verify email link resolves correctly.
3. Password reset request -> email is sent.
4. Password reset confirm succeeds.
5. Logs show successful MAIL_SERVICE calls with no elevated 5xx rate.

Rollback plan

If regressions occur:

1. Re-point auth worker MAIL_SERVICE back to cosmos-mail-worker (or staging equivalent).
2. Redeploy auth worker.
3. Re-test verification/reset email flows.

Rollback target: under 15 minutes.

Checklist

• bookmarks-mail-worker deployed in staging
• Staging verification/reset emails validated
• bookmarks-mail-worker deployed in production
• Auth worker MAIL_SERVICE switched
• Production verification/reset emails validated
• Monitoring clean for 48 hours