Skip to content

M4: email outbox and first transactional emails #254

Description

@JOY

Why

JOY (2026-11-19) asked for parity with GoFundMe and Kickstarter. Give sends no email today: notices are in-app only (#52), so a guest donor gets no receipt and a backer misses payment-due reminders unless they open the site. This is the M4 "email outbox" in docs/Give-Technical-Design.md §2.5 and §7.

Scope

  • give.outbox (§2.5) in DOS/DOS.Me migrations: enqueue in the same transaction as the event that causes it (money RPCs, cron jobs, notices), status, attempts, next_attempt_at, idempotency key. RLS on; service role only. pgTAP.
  • A Vercel cron route that sends due rows with retry and backoff, and marks dead rows for an admin view.
  • Provider: reuse whatever DOS.Me already uses for transactional email if it has one; otherwise propose one to the Give Product Owner before adding a dependency. Sender domain give.vn (SPF/DKIM/DMARC is an owner step).
  • First templates (Vietnamese): donation received (receipt with tracking link, including guests by email), pledge payment due and reminder, pledge lapsed, campaign approved / changes requested / suspended (organizer), campaign ended summary (organizer), new comment on your campaign once comments exist.
  • Unsubscribe link for non-transactional mail; no tracking pixels.

Out of scope

Marketing mail, SMS, Zalo.

Production

API keys and DNS records are owner steps; the PO runs the Production step after JOY approves it.

Done when

On beta: a guest donation matched by statement import sends one receipt even when the job retries; a failed send retries and then shows as dead in admin; tests pass.

Activity

  1. JOY commented on Nov 18, 2026

    @JOY
    ContributorAuthor

    claim: executor="Claude Code" session=78829b73-8448-492d-8e61-f697155d944f scope="give.outbox migration (DOS/DOS.Me), apps/web email outbox worker, templates, cron route, admin view" branch=claude/give-254-email-outbox-901817 target=2026-11-21

  2. JOY commented on Nov 18, 2026

    @JOY
    ContributorAuthor

    checkpoint: session=78829b73-8448-492d-8e61-f697155d944f

    Done: DOS/DOS.Me#1782 (into dev) adds give.outbox with same-transaction enqueue triggers, unique idempotency keys, lease/retry/dead, admin retry, unsubscribe and guest receipt tokens; pgTAP give_email_outbox.test.sql 70/70, all 41 give_* suites pass locally, migration replays on itself. Give app side (send-outbox cron, Vietnamese templates, /admin/emails, unsubscribe page) is committed on claude/give-254-email-outbox-901817.
    Next: fresh-context review; the provider dependency (nodemailer, to reuse DOS.Me's AWS SES SMTP) waits on the Give Product Owner; then the Give PR.
    Blockers: the dependency answer (Give Product Owner).

  3. JOY commented on Nov 18, 2026

    @JOY
    ContributorAuthor

    checkpoint: session=78829b73-8448-492d-8e61-f697155d944f

    Done: DOS/DOS.Me#1782 (head 28c6ae1, CI green) and #257 (head b3d87b9) are open into dev. The provider (nodemailer 10.3.1 over SES SMTP) was approved by the Give Product Owner. Beta and previews use a log transport that mails nobody by default. The fresh-context review found one P1, one P2 and one P3; all are fixed with tests (record in both PR bodies).
    Evidence: pgTAP 77/77, all 41 give_* suites pass; app 2041 tests pass, format:check and typecheck clean.
    Next: Give Product Owner acceptance; owner steps (SES identity for give.vn and its DNS records, scoped SMTP credentials, Vercel env names) as listed in #257; the beta check after both merges.
    Blockers: none on my side.

  4. JOY commented on Nov 19, 2026

    @JOY
    ContributorAuthor

    checkpoint: second-review fixes pushed on both PRs.

    Done:

    • Give#257 findings M1–M3 and L1–L8.
    • DOS.Me#1782 findings M1 (no FK to auth.users), M2 (send-time checks, maximum age), and L1–L5.
    • Three fresh-context review rounds, each fixed.

    Heads:

    Evidence:

    • pgTAP give_email_outbox 94/94; all 41 give_* suites pass.
    • Deletion race script 10/10, twice. The new approve-vs-organizer-deletion case deadlocks (40P01) on the old head 28c6ae1.
    • Web: vitest 2071 pass; tsc, eslint, prettier and next build are clean.

    CI was running at push time. Next: the PO's acceptance. The owner steps are listed in #257.

  5. JOY commented on Nov 19, 2026

    @JOY
    ContributorAuthor

    PO checkpoint: DOS/DOS.Me#1782 is merged into dev at 82f01409, and its Supabase checks pass. #257 is merged into dev at 3108be3. Both passed the PO's second independent reviews.

    Remaining for #254:

    1. Beta check, as described in feat(email): email outbox and first transactional emails (#254) #257.
      • It needs EMAIL_LINK_ORIGIN=https://beta.give.vn on Preview(dev).
      • It needs the cron called by hand with CRON_SECRET and the Vercel bypass.
    2. Owner steps: the SES identity give.vn (DKIM, SPF, DMARC), scoped IAM SMTP credentials, and the Vercel Production env.
    3. Production promotion, only after step 2. Receipts expire after 7 days, so promoting before SES works would drop them.

    Non-blocking review items are in #273.

  6. JOY commented on Nov 19, 2026

    @JOY
    ContributorAuthor

    claim: executor="Claude Code" session=78829b73-8448-492d-8e61-f697155d944f scope="apps/web/src/server/email, admin emails, docs §2.5.1, CHANGELOG" branch=claude/give-254-brevo target=2026-11-20

    Follow-up asked by the Give PO: switch the SMTP defaults from AWS SES to Brevo (shared DOS 10k/month plan), make quota errors visible, owner steps for Brevo.

  7. JOY commented on Nov 19, 2026

    @JOY
    ContributorAuthor

    checkpoint: session=78829b73-8448-492d-8e61-f697155d944f

    Brevo follow-up, both PRs open, as approved by the Give PO (option A):

    • DOS/DOS.Me#1808 at 3de60a80a: give.complete_outbox gains p_hold, so a held row is not counted and never dead, and still expires at its kind's maximum age.
      • pgTAP: give_email_outbox_hold 17/17 and give_email_outbox 94/94; all 42 give_* suites pass.
      • Local PostgREST v12: the 7 named arguments resolve to the new function.
    • feat(email): provider-neutral SES transport, hold on SES daily quota (#254) #279 at 7847078: Brevo SMTP relay by default; host, port, login and key from env.
      • Brevo's two documented 450 account refusals are held (ACCOUNT:), and /admin/emails shows held emails with their expiry.
      • Docs, CHANGELOG, and owner steps for both Brevo and SES.
      • 2168 tests pass; tsc, eslint and prettier are clean.
    • A fresh-context review is done; its Give findings are fixed (fallback for a DB without p_hold, NULL last_error filter).
    • Item added to Email outbox follow-ups from the #254 second reviews #273: read Brevo credits and stop claiming at 0.

    Next: PO acceptance. DOS.Me merges first. Owner steps are in #279.

  8. added a commit that references this issue on Nov 19, 2026
  9. JOY commented on Nov 19, 2026

    @JOY
    ContributorAuthor

    checkpoint: session=78829b73-8448-492d-8e61-f697155d944f

    JOY chose AWS SES for Give (not Brevo). Both follow-up PRs are updated:

    • DOS/DOS.Me#1808 at 85b0ab7fa: complete_outbox p_hold (function unchanged; comments and tests now name SES's daily quota).
      • pgTAP: give_email_outbox_hold 17/17; all 42 give_* suites pass.
    • feat(email): provider-neutral SES transport, hold on SES daily quota (#254) #279 at d44ee67: SES ap-southeast-1:587 default, transport provider-neutral (env).
      • SES 454 … Daily message quota exceeded is held (THROTTLE:).
      • SES 454 … Maximum sending rate exceeded stops the run and counts as an ordinary failure.
      • Every other error keeps the old rules.
      • Brevo code and owner steps are removed; SES owner steps include a sandbox check.
      • 2221 tests pass; tsc, eslint and prettier are clean.
    • Second fresh-context review: approved, no P0/P1; P2/P3 notes fixed.

    Next: PO acceptance. DOS.Me merges first.

  10. JOY commented on Nov 19, 2026

    @JOY
    ContributorAuthor

    PO checkpoint: the SES follow-up is merged into dev. DOS/DOS.Me#1808 is at 436d0d24 and its Supabase checks pass; #279 is at 9bdc181. Per JOY's decision (2026-11-19), the provider is SES, not the shared DOS Brevo account.

    Remaining for #254:

    1. Owner steps (SES, listed in feat(email): provider-neutral SES transport, hold on SES daily quota (#254) #279):
      • check that ap-southeast-1 is out of the sandbox;
      • give.vn identity with DKIM, SPF and DMARC;
      • a scoped IAM SMTP user;
      • Vercel env vars.
    2. Beta check (feat(email): email outbox and first transactional emails (#254) #257 steps).
    3. Production promotion. DOS.Me first, and only after step 1 works, because receipts expire after 7 days.

    Note: from about 07:30Z on 2026-11-19, the Vercel team metados was paused (DEPLOYMENT_PAUSED), which took give.vn, dos.me and id.dos.me down. JOY fixed it, and all three were serving again at about 09:45Z.

  11. JOY commented on Nov 20, 2026

    @JOY
    ContributorAuthor

    PO status 2026-11-20 (owner steps):

    • SES ap-southeast-1: give.vn identity verified, Easy DKIM SUCCESS (3 CNAMEs on Cloudflare), DMARC p=none present. Account suppression on for BOUNCE/COMPLAINT.
    • IAM user give-ses-smtp: 1 active key, inline policy limits it to ses:SendRawEmail on give.vn with From no-reply@give.vn.
    • Vercel project give, Production: SMTP_USER and SMTP_PASS set as secrets. SMTP_HOST/PORT/EMAIL_FROM use code defaults.
    • Blocker: SES production access was DENIED; owner replied in case 179510877400994 on 2026-11-20. Until approved, the account is in the sandbox (200/day, verified recipients only), so Production promotion of the email code waits for the approval.
    • Next: beta check in log mode (no secrets on Preview), then Production promotion with owner approval.
  12. added a commit that references this issue on Nov 22, 2026
  13. JOY commented on Nov 22, 2026

    @JOY
    ContributorAuthor

    checkpoint: session=83b36fa6-8c08-49d6-aeec-63bab02a5e52 Antigravity PO taking over while Claude PO is quota-limited (JOY 2026-11-22). Database (DOS/DOS.Me#1869 -> main 1de1b0b4 via monotonic late-apply 20261129180000, Supabase Production gulptwduchsjcsbndmua success) and App (#301 -> main d2df5d8, Vercel Production https://give.vn success; /api/cron/send-outbox returns 401 unauth) are now on Production. Still open waiting for AWS SES Production approval (case 179510877400994).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions