Solutions/Engineers

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.

1
Confirmoutbox INSERT
An outbox entry is written atomically, in the same transaction as the campaign state change.
2
PollFOR UPDATE SKIP LOCKED
Workers claim rows concurrently. No duplicate sends, even under retry.
3
Fan out1 call / n batched recipients
Each recipient is batched into a single Resend API call.
4
Recordprovider_event_id UNIQUE
Delivered, opened, bounced and complained events arrive via webhook and are written idempotently.
worker / poll outboxsimplified
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

At rest
Encrypted with AES-256-GCM before storage.
In use
Decrypted only at read time to query your user table. Read-only queries, no writes, ever.
Never
Logged, returned in any API response, included in webhook payloads, or passed to Resend.

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

WhatKeyed byTTL
Resend HTTP clients (Caffeine)API key1h
Onboarding OAuth sessionsession token30m
Campaign + email provider during fan-outcampaign / account id30s

30 seconds is short enough to reflect config changes, long enough to avoid repeated reads across a large recipient list.

The stack

Backend
Spring Boot (Java 25), package-by-feature modular monolith, sealed interfaces for domain results
Database
PostgreSQL on Railway, Flyway migrations
Frontend
Next.js 16 App Router, TanStack Query, shadcn/ui
Delivery
Resend (bring your own key)
Billing
Stripe
Deploy
Railway (API, worker, webhooks), Vercel (frontend)

Source and documentation

Don't take our word for it. The full architecture is documented in the public GitHub org.

broadcastmail-iopublic
ARCHITECTURE.mdSystem overview, campaign lifecycle, outbox pattern, plan enforcement. Mermaid diagrams.
DATABASE.mdFull schema with table descriptions.
DECISIONS.mdKey architectural decisions and the reasoning behind each.
SECURITY.mdThreat model and security design.

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.

Get oriented
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.
How to work together
-Open an issue before anything non-trivial: the problem, your proposal, alternatives considered.
-Branch from main with a feat/, fix/ or chore/ prefix.
-Tests use Given/When/Then comments. Keep that style.
-PRs are squash-merged to main.
Where help matters most
-Edge cases in fan-out and webhook handling
-Bug reports with clear reproduction steps
-Docs gaps you hit during setup. If it confused you, it will confuse the next person.

Read-only, encrypted, open source. Try it on your project.