Built by a developer. Designed to hold up in production.
Exactly how BroadcastMail works under the hood: the data model, the reliability patterns, and why each decision was made. No black boxes.
Overview
If you're evaluating BroadcastMail for a production Supabase app, you probably want to understand exactly what access you're granting before you connect.
This page is for you. Full architecture, real decisions, honest tradeoffs.
How fan-out works
Sending a campaign is not one synchronous request. It's four stages, each safe to retry.
SELECT id, campaign_id, recipient FROM outbox WHERE status = 'pending' ORDER BY created_at LIMIT 100 FOR UPDATE SKIP LOCKED;
A transient Resend failure doesn't silently drop emails: they sit in the outbox until fanned out. A duplicate webhook doesn't double-count your open rate.
Why the outbox pattern, not WAL/CDC
First, the practical reason. Railway, where BroadcastMail runs, doesn't expose replication slots. WAL-based CDC isn't available without migrating infrastructure.
Second, the real one. The outbox pattern is correct even when WAL is available. CDC is for reacting to writes from systems you don't control. BroadcastMail owns its writes, so writing to an outbox in the same transaction as the campaign state change gives exactly-once semantics at the application level, without relying on the replication layer.
How your database access is scoped
Authentication and session security
Set-Cookie: session=…; SameSite=None; Secure; HttpOnly
Cookie-based auth plus CSRF tokens protect cross-origin requests between the Vercel frontend and Railway backend. API keys are never stored in localStorage, a deliberate choice to avoid XSS exposure.
Webhook idempotency
Resend webhooks are deduplicated on the svix-id header, stored as provider_event_id with a UNIQUE constraint. A duplicate event, common under retries, is silently ignored rather than double-counting metrics or triggering a second status transition.
provider_event_id TEXT NOT NULL UNIQUE -- duplicate svix-id → unique violation → ignored
Unsubscribe handling
Every email carries a List-Unsubscribe header and a one-click link. Tokens are signed with JJWT using a secret shared between the API and worker. Clicking adds the address to a suppression list, and later campaigns skip it at fan-out, before any Resend call is made.
Caching
30 seconds is short enough to reflect config changes, long enough to avoid repeated reads across a large recipient list.
The stack
Source and documentation
Don't take our word for it. The full architecture is documented in the public GitHub org.
Want to help make this better?
BroadcastMail is open source. If you care about developers having an honest tool for emailing their users, one that doesn't lock you in, doesn't put its branding on your emails, and works the way you'd build it yourself, this is worth contributing to.
ARCHITECTURE.md: system overview with Mermaid diagrams. Start here.DECISIONS.md: read before proposing structural changes, so we build on shared context instead of relitigating closed decisions.DEVELOPERS.md: in each repo. Local setup, branch conventions, running tests.