DEV Community: Srinivasa Rao

The Webhook Bug That Passed Every Test and Every Code Review

Srinivasa Rao — Sun, 26 Jul 2026 07:58:51 +0000

When a subscriber disappears from a list, nobody gets an error. The campaign sends, the contact count is one fewer than expected, and unless someone is watching very carefully, you might never know you lost a subscriber who had nothing to do with that send.

This is about a bug I found in my own code that did exactly that. It lived in a bounce handler, invisible to every test I wrote and every review pass I ran — including one where I explicitly sat down to look for security issues.

This is Part 3 of a series on building a multi-tenant email service with FastAPI and Resend.

Part 1 — Building the service: one Resend account, multiple customer domains, contacts, segments, campaigns.
Part 2 — Making sends safe to retry: idempotency keys, per-recipient status tracking, the chunk key that was never actually retried.
Part 3 (this one) — A webhook handler that looked correct and wasn't.

The full working code is on GitHub: srinivaspavuluri/resend-fastapi

Quick context: the data model

The service manages email sending for multiple customers — think of each customer as a separate business using the same platform. The relevant tables:

Customer — one row per tenant, each with a verified sending domain
Contact — email addresses, scoped to a specific customer via customer_id
Campaign — a send from a customer to their contacts
CampaignRecipient — one row per contact per campaign; stores the resend_email_id that Resend assigns to each individual email

When a campaign sends, every contact gets a CampaignRecipient row:

db.add(CampaignRecipient(
    campaign_id=campaign_id,
    contact_id=contact.id,
    resend_email_id=result.resend_email_id,
    status="queued",
))

That resend_email_id matters. It comes back in every webhook event Resend fires.

The bounce handler

Auto-unsubscribing on bounce is important for sender reputation. Resend monitors bounce and complaint rates on your account — if they climb too high, your sending ability gets restricted. So when a bounce arrives, you want to unsubscribe that contact immediately and automatically.

My SECURITY.md noted this under "What's Done Well":

Bounce/complaint auto-unsubscribe — protects sender reputation, scoped correctly.

That credit was wrong.

What the original handler did

The bounce handler received an event from Resend with a payload like this:

{
  "type": "email.bounced",
  "data": {
    "email_id": "ae2faec7-...",
    "to": ["user@gmail.com"]
  }
}

The original unsubscribe logic took the to field — the recipient email address — and used it to find the contact to unsubscribe:

# The original approach
to_emails = data.get("to", [])
if isinstance(to_emails, str):
    to_emails = [to_emails]

await db.execute(
    update(Contact)
    .where(Contact.email.in_(to_emails))   # no customer_id filter
    .values(is_subscribed=False)
)

Find contacts with that email. Set them to unsubscribed. Simple.

The problem is what "contacts with that email" actually means.

The gap

The Contact table looks like this:

class Contact(Base):
    id = Column(String, primary_key=True)
    customer_id = Column(String, ForeignKey("customers.id"), nullable=False)
    email = Column(String, nullable=False)
    is_subscribed = Column(Boolean, default=True)

There is no unique constraint on email across the whole table. It's unique per customer, not globally. The same address — user@gmail.com — can legitimately exist as a Contact row under Customer A and Customer B. That's not a design flaw; it's the point of multi-tenancy. These are two separate businesses. Their subscribers don't know about each other.

But the original bounce handler didn't know or care about any of that. It queried Contact.email.in_(to_emails) with no customer_id filter. If both Customer A and Customer B had user@gmail.com in their contact lists, and Customer A's email to that address bounced, the handler would unsubscribe both contacts — Customer A's and Customer B's.

Customer B just lost a subscriber they never sent to. No error raised. No log entry about the wrong tenant. The contact row just flips to is_subscribed = False and the next campaign quietly skips them.

Why every test missed it

I had tests covering the bounce handler. They verified that after a bounce event, the right contact ended up unsubscribed. Every test passed.

But every fixture used a single customer. One customer, one contact, one campaign, one send. With only one customer in the database, there's no ambiguity about which Contact row a raw email query hits — it gets the right one every time.

The bug is invisible in that setup. It only appears when you have two customers with an overlapping contact email, and that's a production condition, not one I thought to simulate. I never wrote the test that would have caught this because I never asked "what happens if the same email exists under a different customer?"

The tests weren't wrong. They verified exactly what I asked them to verify. I just didn't ask the right question.

Why the security review missed it too

Before writing Part 2, I ran a deliberate security pass over the codebase. I went handler by handler, route by route, and wrote up findings in SECURITY.md.

The bounce handler made the "What's Done Well" list. The note said it was "scoped correctly."

What I was actually reviewing during that pass was the signature verification — Resend signs every webhook with a Svix HMAC signature, and I was checking whether the verification logic was sound. I was asking "can this endpoint be spoofed or replayed?"

That's the right question for a webhook security review. But it's not the only question. I wasn't asking "does this update the right rows?" because the handler looked like it did. You read Contact.email.in_(to_emails) and you think: yes, that's the email address that bounced, that's the contact to unsubscribe. It's only wrong if you're holding the full multi-tenant data model in mind at the same time — and in a review pass covering a dozen findings, I wasn't.

The bug passed because I asked one security question thoroughly and missed a different one entirely.

The fix

The fix uses data that was already there.

Every CampaignRecipient row stores a resend_email_id. The bounce event carries that same ID. That row links back to a specific contact_id — one that belongs to exactly one customer, because it came from one campaign, which belongs to one customer.

So instead of querying contacts by raw email, derive the contact through the recipient row:

elif event_type == "email.bounced":
    email_id = data.get("email_id")
    if email_id:
        await db.execute(
            update(CampaignRecipient)
            .where(CampaignRecipient.resend_email_id == email_id)
            .values(status="bounced", updated_at=now)
        )
        # Derive contact_id from CampaignRecipient, not from raw email.
        # The same email can exist under multiple customers — matching on email
        # with no customer_id filter would unsubscribe the wrong tenant's contact.
        contact_id_subq = (
            select(CampaignRecipient.contact_id)
            .where(
                CampaignRecipient.resend_email_id == email_id,
                CampaignRecipient.contact_id.isnot(None),
            )
            .scalar_subquery()
        )
        await db.execute(
            update(Contact)
            .where(Contact.id == contact_id_subq)
            .values(is_subscribed=False)
        )
        await db.commit()

resend_email_id → CampaignRecipient.contact_id → Contact.id.

Each step follows a relationship that's already scoped to the right tenant. There's no raw email lookup anywhere. Cross-tenant access is structurally impossible because there's no point in the chain where the query spans customers.

The lesson

Email addresses feel like natural lookup keys. They're unique in the human sense — one person, one address — and they're right there in the webhook payload. When a bounce arrives, your first instinct is: find the contact with that email, unsubscribe them.

But in a multi-tenant system, "unique in the human sense" and "unique in your database" are different things. An email address is unique per customer. Globally, across all customers, it isn't.

When you use a value that's globally unique in the real world but only tenant-scoped in your data model, you're querying at the wrong level of isolation. The query won't error. It'll return rows — plausible-looking rows — and update ones you never intended to touch.

The correct instinct is to follow the relationship chain that the data model already enforces. resend_email_id → CampaignRecipient → contact_id works because every link in that chain belongs to one customer. The relationship scope is the tenant scope. You don't need to add a customer_id filter anywhere because the chain never leaves the right tenant.

This is the kind of bug that doesn't announce itself. Nothing crashes. No test fails. No security scanner flags it. You find it by asking a question that your normal review process wasn't designed to ask: does this query respect the tenant boundaries my data model defines?

What else the full review found

This bounce handler bug was the headline finding, but the same review pass surfaced three others:

A cascade gap. The endpoint for deleting a customer claimed to delete all their associated data, but the ORM relationship had no cascade="all, delete" set, and the SQLite dev environment never had PRAGMA foreign_keys = ON active. Campaign and recipient rows were silently orphaned on customer delete in dev. Postgres would have enforced the foreign key constraint and actually deleted them. Fixed with the cascade option on the relationship.

A dead route. GET /{customer_id}/campaigns/{campaign_id} was defined in two different routers. Registration order meant one copy was always unreachable. Removed it.

A replay window. The Svix signature verification had no timestamp freshness check, meaning a captured valid payload and signature could be replayed at any point in the future. Added a five-minute tolerance check before the HMAC comparison.

None of these three are as consequential as the bounce handler bug. The cascade gap is a data hygiene problem in dev. The dead route is harmless. The replay window is a real vulnerability, but exploiting it requires capturing a valid signed payload first. The bounce handler bug was uniquely dangerous because the failure mode was completely silent — no crash, no error, just data quietly drifting in the wrong direction.

Up next

The next piece in this series is a smaller fix with a disproportionate teaching value.

The idempotency check at the top of the send endpoint — the one that short-circuits if a campaign with that key already exists — returns a raw 500 from an unhandled IntegrityError instead of the clean 409 it's supposed to return. One exception catch to fix it. But where you put that catch, and why it has to be there specifically, surfaces something worth understanding about the relationship between application-level error handling and database-level constraints.

That's Part 4.

Fixing a Double-Send Bug Taught Me Idempotency Keys Aren't Enough

Srinivasa Rao — Sun, 28 Jun 2026 15:40:55 +0000

A reader comment on my last article did more code review than I expected from a Dev.to comment section.

After I published the multi-tenant email piece — Resend + FastAPI, one backend, per-customer domains — Alex Shev left this:

"Multi-tenant email gets tricky because the hard part is not sending one message; it is preserving tenant boundaries across templates, sender identity, suppression lists, audit logs, and retries. The docs usually cover the happy-path API call. The production system is all the isolation around it."

Five gaps in one comment. I went looking for the smallest one to fix first — retries — assuming it'd be a quick follow-up. It wasn't. Tracing it properly surfaced two more bugs I hadn't written into the original code on purpose, and one habit I'm changing going forward: when I add a safety mechanism, I now have to prove it actually fires before I get to call it done.

This is that trace, in the order I actually found things — not cleaned up into a tutorial.

The bug retries actually have

The original /send endpoint batches 100 emails per Resend API call and loops until every contact is covered. If you have 250 subscribers, that's 3 calls. If call #2 throws — rate limit, network blip, Resend having a bad five minutes — the loop stops. The first 100 are sent. The last 150 are not. The endpoint returns a 502.

Nothing about that response tells the caller which 100 went out. The obvious move — retry the request — re-sends to all 250, because the retry has no memory of the first attempt. The 100 who already got the email get it twice.

That's the gap Alex's comment was naming. The fix everyone reaches for is idempotency keys. I reached for them too. They were necessary. They were not sufficient, and the way they weren't sufficient is the actual point of this article.

Attempt 1: an `Idempotency-Key` header

Resend supports an Idempotency-Key header on both /emails and /emails/batch — send the same key with the same payload twice, get the same response back, no second email. I wired that into send_single and send_batch:

# app/services/resend_service.py
def _auth_headers(idempotency_key: str = "") -> dict:
    headers = {
        "Authorization": f"Bearer {resend.api_key}",
        "Content-Type": "application/json",
        "Accept": "application/json",
    }
    if idempotency_key:
        headers["Idempotency-Key"] = idempotency_key
    return headers

The detail that matters more than the header itself: where the key comes from. My first instinct was to generate one server-side per request — uuid4(), done. That's wrong, and it's wrong in a way that's easy to miss because the code runs fine and the tests pass. A server-generated key changes every time the server creates a new request object, which includes every retry. The client resending the exact same logical request gets a fresh key each time, and Resend — correctly, by design — treats a new key as a new send. You've built idempotency infrastructure that's idempotent against nothing, because the one thing that's supposed to stay constant across a retry is the one thing you're regenerating on every attempt.

The key has to come from the caller, survive across their retry, and identify the request, not the attempt:

# app/routers/email.py
async def send_email(
    customer_id: str,
    body: SendEmailRequest,
    idempotency_key: Optional[str] = Header(None, alias="Idempotency-Key"),
    db: AsyncSession = Depends(get_db)
):
    ...
    campaign_id = idempotency_key or new_id()

    existing_result = await db.execute(select(Campaign).where(Campaign.id == campaign_id))
    existing_campaign = existing_result.scalar_one_or_none()
    if existing_campaign:
        if existing_campaign.status == "sent":
            return { "success": True, "campaign_id": existing_campaign.id, ... }
        raise HTTPException(status_code=409, detail={...})

Same Idempotency-Key, same campaign — if it already finished, return the cached result instead of sending again. If it's still mid-flight or only partially done, 409 instead of a silent re-send. That part worked exactly as intended once I tested it against the real API: same key plus same payload returns the identical response on both /emails and /emails/batch, no duplicate delivery. Different payload under the same key gets a 409 invalid_idempotent_request from Resend itself.

But notice what the 409 branch does for a campaign stuck in "partial": it tells the caller there's unfinished work and stops. It does not tell them how to finish it. That gap is the next bug.

Attempt 2: the 409 was pointing at a worse bug than the one it caught

My first version of that error message read:

"A campaign with this Idempotency-Key already exists but did not finish. Start a new campaign with a different Idempotency-Key to retry."

Read that literally and follow the advice: a new key means a new campaign, which means the send loop runs again from contact #1 — including the ones who already got the email in the failed attempt. The error message I wrote specifically to prevent a double-send was itself instructing the caller into one. I'd fixed the retry path and left the recovery path wide open.

Fixing it properly meant tracking who was actually emailed, not just how many. I added a CampaignRecipient row per contact per chunk, written the moment Resend's batch call returns an ID for them:

# app/models.py
class CampaignRecipient(Base):
    """One row per contact per campaign. Populated when the batch call returns
    email IDs, then updated by the webhook handler as delivery events arrive."""
    __tablename__ = "campaign_recipients"

    id = Column(String, primary_key=True, default=new_id)
    campaign_id = Column(String, ForeignKey("campaigns.id", ondelete="CASCADE"), nullable=False)
    contact_id = Column(String, ForeignKey("contacts.id", ondelete="SET NULL"), nullable=True)
    resend_email_id = Column(String(255), nullable=True, index=True)
    status = Column(String(50), default="queued")
    updated_at = Column(DateTime, default=datetime.utcnow)

Then a resume_from_campaign_id field that excludes anyone already in that table for the failed campaign:

# app/routers/email.py
if body.resume_from_campaign_id:
    resume_campaign = ...  # fetch + verify it belongs to this customer
    if resume_campaign.status != "partial":
        raise HTTPException(status_code=400, detail=(
            f"Cannot resume a campaign with status '{resume_campaign.status}'. "
            "Only 'partial' campaigns can be resumed."
        ))
    already_sent_subq = select(CampaignRecipient.contact_id).where(
        and_(
            CampaignRecipient.campaign_id == body.resume_from_campaign_id,
            CampaignRecipient.contact_id.isnot(None),
        )
    )
    query = query.where(Contact.id.notin_(already_sent_subq))

Two details in that snippet earned their place the hard way, not by design upfront.

The .isnot(None) line. CampaignRecipient.contact_id is nullable — it's set to SET NULL if a contact gets deleted later. SQL's NOT IN uses three-valued logic: if the subquery returns even one NULL, the entire NOT IN comparison evaluates to unknown — for every row, not just the one tied to the NULL. Without that filter, one deleted contact silently turns "exclude everyone already emailed" into "exclude no one," and resume would have matched zero people for reasons that wouldn't show up in any test using a normal dataset. It only shows up once a contact is deleted between the failed send and the resume — which is exactly the kind of thing that doesn't happen in a demo and does happen eventually in production.

The != "partial" check. I originally allowed resuming anything that wasn't "sent" — which included "sending". That's a race: resume an in-flight campaign and you now have two processes building exclusion lists against a table that's still being written to mid-send. Restricting resume to "partial" only closes that window.

Both came from asking "what's the actual claim this code is making, and what has to be true for the claim to hold" rather than "does this pass the test I already wrote." The NULL trap especially wouldn't show up under the conditions most people test with.

Lesson 1: an idempotency key at the wrong layer is theater

Here's the one I didn't expect. Each chunk inside the send loop gets its own key:

for i in range(0, len(recipients), 100):
    chunk_key = f"{campaign_id}/batch-{i // 100}"
    chunk_results = await send_batch(..., idempotency_key=chunk_key)

The idea: if the chunk-level call to Resend gets retried, Resend's own dedup catches it independently of anything my database is doing. Defense in depth. It reads like good defensive engineering, and I believed it was protecting something right up until I traced what actually calls this code with a repeated chunk_key.

Nothing does.

The top-level check at the start of the endpoint short-circuits on campaign_id before the loop is ever reached a second time — a retry with the same Idempotency-Key either returns the cached "sent" result or a 409, full stop. resume_from_campaign_id, the other path that re-enters the loop, always builds a new campaign_id and therefore new chunk keys, every time. There is no code path, anywhere in this service, that calls send_batch twice with the same chunk_key. Resend's per-chunk dedup is sitting behind a door nothing in my codebase ever knocks on.

It's not actively harmful — it's just inert. But inert security code is worse than no code, because it occupies the mental slot of "this is handled" without doing anything. If a future change to the resume logic accidentally did start reusing a campaign_id, I'd reach for "the chunk keys protect us there" and be wrong, because the lack of replay was never actually guaranteed by the chunk keys — it was guaranteed by the resume logic always minting fresh ones, which is a property of completely different code.

The lesson I'm taking into the next thing I build: an idempotency key only protects you at the layer where a retry can actually recur. If you can't point to the specific code path that would call the same operation twice with the same key, you haven't added protection — you've added a key that looks like protection. Worth tracing before you trust it, not after.

Lesson 2: a forensic log is only real once you've checked it's emitting

The chunk-key finding leaves a real gap, not a cosmetic one: if a chunk's httpx call to Resend times out after Resend has already accepted and started sending it, the exception handler marks the campaign "partial" — but no CampaignRecipient rows exist for that chunk, because the response never came back far enough to read the email IDs out of it. Resume can't exclude contacts it has no record of. Building the full fix (a CampaignChunk table tracking attempt status independent of the response) felt like more machinery than this risk currently justifies, so I made a deliberate call to document it as a known v1 limitation instead of building it — more on why below.

As a cheap mitigation in the meantime, I added a log line before each chunk dispatch, specifically so a human could reconstruct what happened if a duplicate complaint ever surfaced:

logger.info(
    "send_batch attempt campaign_id=%s chunk_key=%s contact_ids=%s",
    campaign_id, chunk_key, [c.id for c in chunk_contacts],
)

I logged the contact IDs, not just a count — a count can't be turned back into "which specific people" later, especially after the contact table has drifted since the incident. IDs can.

Then I checked whether the line was actually showing up anywhere, mostly out of habit. It wasn't. Nowhere in the project did anything call logging.basicConfig() or set a level — which means Python's root logger was sitting at its default, WARNING, and silently swallowing every single logger.info() call in the file, and in the webhook handler too. The mitigation I'd built specifically to cover the one failure window I couldn't close in code was never running. Adding logging.basicConfig(level=logging.INFO, ...) to app/main.py and watching the output actually appear in stdout was the fix — one line, after the fact.

This is the same shape of mistake as the chunk-key one: code that's structurally correct and semantically inert. The difference is that this one would have been invisible right up until the moment I actually needed the log — which is the worst possible time to discover a safety net was never connected. The same incident that needs the forensic trail is the same incident that would have revealed it wasn't there. I'm treating "did I confirm this actually executes" as a separate, mandatory step now, distinct from "did I write code that should execute" — they're not the same claim, and only one of them is checked by reading the diff.

What's still open, on purpose

A couple of things I'm leaving unfixed, with the reasoning written down rather than left implicit:

The timeout-after-accept window. Closing it properly means a CampaignChunk table — one row per chunk attempt, written before the Resend call so an attempt is on record even if the response never comes back, with its own status independent of whether CampaignRecipient rows exist yet. That's a real schema change, not a one-line fix, and it's solving for a narrow race (network failure in the few-hundred-millisecond window between Resend accepting and the response reaching the client) that hasn't actually happened yet in this project. Documenting the gap and the mitigation felt like the more honest call than guessing at a design for a failure mode I haven't observed. Chasing it properly would be its own investigation.

Concurrent duplicate keys. Two requests with the same Idempotency-Key arriving close enough together can both pass the "no existing campaign" check before either one commits a row. Low probability for how this service is actually called, but unhandled — it would currently surface as a raw 500 instead of a clean 409. Noted, not fixed yet.

The actual takeaway

Idempotency keys are the right tool. They're also not a single fix you add once — they're a claim about a specific code path, and the claim is only true if you can trace the exact retry that would hit it. The header on /emails and /emails/batch protects the layer where Resend itself might see a duplicate call. The campaign_id check protects the layer where a client retries the whole request. Neither one automatically covers the layer in between — per-chunk attempts — and I only found that out by asking "what specifically calls this twice" instead of "does this look right."

Same with the logging fix: a safety net you haven't watched fire isn't a safety net, it's an assumption with good intentions.

Code's on GitHub if you want to see the rest: github.com/srinivaspavuluri/resend-fastapi

That comment named five gaps. Retries are the one I've actually closed the loop on here. The remaining four — suppression lists, audit logs, sender identity isolation, and the timeout-after-accept window the chunk-key finding left open — are candidates for what comes next, in some order. Sender identity isolation is the one I understand the least; if anyone has a strong opinion on it, I'd like to hear it before I try to write about it.

Found a hole in this one too? That's kind of how the last one went, and it made the article better. Comments are open.

Building a Multi-Tenant Email System with FastAPI and Resend: What the Docs Don't Tell You

Srinivasa Rao — Thu, 11 Jun 2026 23:44:04 +0000

When I was tasked with building an email feature that would let multiple clients send emails from their own domains — all through a single backend — I assumed Resend's Audiences and Broadcasts API would handle everything. The docs make it look clean.

It isn't.

After working through the actual implementation, I realized that Resend's Segments have no API filtering support, Audiences and Contacts are completely separate from Domains with no native relationship, and Broadcasts work but don't give you the per-customer control you need in a multi-tenant setup.

The pattern that actually works is simpler: use Resend only for domain verification and email delivery, and own the contact and segment layer yourself in your database.

This article walks through exactly how I built that in Python with FastAPI — including the testing approach that lets you verify everything works without owning a real domain or paying for API calls.

What We're Building

A backend service where:

Multiple customers (your clients) each send emails from their own verified domain (acme.com, betacorp.com)
All sending goes through a single Resend account and one API key
Contacts, segments, and campaign history are stored in your own database — not in Resend
Delivery events (sent, bounced, opened, clicked) come back via Resend webhooks

Here's the architecture:

Your Customers
    │
    ▼
FastAPI Backend
    ├── Customer A → domain: acme.com     ─┐
    ├── Customer B → domain: betacorp.com  ├──▶ Resend (sending engine only)
    └── Customer C → domain: delta.io    ─┘
    │
    └── Your Database (SQLite locally, PostgreSQL in production)
            ├── customers  (domain mapping + verification status)
            ├── contacts   (owned by customer, with tags)
            ├── segments   (named groups of contacts)
            └── campaigns  (history of every send)

Resend's only job: verify domains and deliver emails. Everything else lives in your database.

The Key Insight About Resend

Before writing a line of code, this is worth understanding clearly.

Resend has two separate worlds:

World 1: Domains + Emails (reliable, full API support)

Add and verify custom domains
Send single emails (POST /emails)
Send batch emails up to 100 at a time (POST /emails/batch)
Webhook delivery events

World 2: Audiences + Contacts + Broadcasts (limited via API)

Audiences and Contacts exist in the API, but Segments are dashboard-only — there's no filtering endpoint
You can't query "send only to contacts where plan = premium" — that endpoint doesn't exist
Domains and Contacts have no relationship in Resend's data model at all

Once I understood this, the solution became obvious: store contacts in my own database and use Resend only as the delivery engine.

Project Setup

pip install fastapi uvicorn sqlalchemy aiosqlite resend \
            python-dotenv "pydantic[email]" httpx svix

For local development, aiosqlite gives you async SQLite with zero setup. Swap to asyncpg for PostgreSQL in production — no code changes needed.

Project structure:

resend-fastapi/
├── app/
│   ├── main.py
│   ├── models.py
│   ├── database.py
│   ├── routers/
│   │   ├── customers.py     # CRUD + domain setup
│   │   ├── contacts.py      # contacts + segments
│   │   ├── email.py         # send endpoints
│   │   ├── campaigns.py     # send history
│   │   └── webhooks.py      # Resend delivery events
│   └── services/
│       └── resend_service.py  # only file that calls Resend
├── tests/
│   ├── conftest.py
│   ├── test_customers.py
│   ├── test_contacts.py
│   ├── test_email.py
│   ├── test_campaigns.py
│   ├── test_webhooks.py
│   └── e2e/
│       └── test_api_e2e.py
├── .env
├── .env.example
├── pytest.ini
└── requirements.txt

.env:

RESEND_API_KEY=re_your_api_key_here
# SQLite for local dev (default — no setup needed):
DATABASE_URL=sqlite+aiosqlite:///./resend_local.db
# PostgreSQL for production:
# DATABASE_URL=postgresql+asyncpg://user:password@localhost/emaildb
# Webhook signing secret (from Resend dashboard):
# WEBHOOK_SECRET=whsec_your_secret_here

Database Models

One design choice worth calling out: I use SQLAlchemy's JSON column type instead of PostgreSQL-specific ARRAY or JSONB. This means the same model code runs on both SQLite (local dev) and PostgreSQL (production) without changes.

# app/models.py
from sqlalchemy import Column, String, Boolean, DateTime, ForeignKey, JSON, Integer
from sqlalchemy.orm import relationship, DeclarativeBase
from datetime import datetime
import uuid


class Base(DeclarativeBase):
    pass


def new_id() -> str:
    return str(uuid.uuid4())


class Customer(Base):
    __tablename__ = "customers"

    id = Column(String, primary_key=True, default=new_id)
    name = Column(String(255), nullable=False)
    domain_name = Column(String(255), nullable=True)
    resend_domain_id = Column(String(255), nullable=True)
    domain_verified = Column(Boolean, default=False)
    created_at = Column(DateTime, default=datetime.utcnow)

    contacts = relationship("Contact", back_populates="customer", cascade="all, delete")
    segments = relationship("Segment", back_populates="customer", cascade="all, delete")


class Contact(Base):
    __tablename__ = "contacts"

    id = Column(String, primary_key=True, default=new_id)
    customer_id = Column(String, ForeignKey("customers.id"), nullable=False)
    email = Column(String(255), nullable=False)
    first_name = Column(String(100), nullable=True)
    last_name = Column(String(100), nullable=True)
    tags = Column(JSON, default=list)        # e.g. ["newsletter", "premium"]
    is_subscribed = Column(Boolean, default=True)
    created_at = Column(DateTime, default=datetime.utcnow)

    customer = relationship("Customer", back_populates="contacts")


class Segment(Base):
    __tablename__ = "segments"

    id = Column(String, primary_key=True, default=new_id)
    customer_id = Column(String, ForeignKey("customers.id"), nullable=False)
    name = Column(String(255), nullable=False)
    created_at = Column(DateTime, default=datetime.utcnow)

    customer = relationship("Customer", back_populates="segments")
    contacts = relationship("Contact", secondary="contact_segments", backref="segments")


class ContactSegment(Base):
    __tablename__ = "contact_segments"

    contact_id = Column(String, ForeignKey("contacts.id", ondelete="CASCADE"), primary_key=True)
    segment_id = Column(String, ForeignKey("segments.id", ondelete="CASCADE"), primary_key=True)
    added_at = Column(DateTime, default=datetime.utcnow)


class Campaign(Base):
    """Records every bulk send — a historical log you can query later."""
    __tablename__ = "campaigns"

    id = Column(String, primary_key=True, default=new_id)
    customer_id = Column(String, ForeignKey("customers.id", ondelete="CASCADE"), nullable=False)
    subject = Column(String(500), nullable=False)
    sent_to_count = Column(Integer, default=0)
    from_address = Column(String(255))
    targeting = Column(JSON, default=dict)  # {"tag": "premium"} or {"segment_id": "..."}
    status = Column(String(50), default="sent")
    sent_at = Column(DateTime, default=datetime.utcnow)

    customer = relationship("Customer", backref="campaigns")

The Campaign model is created automatically every time you call the send endpoint — no manual tracking needed.

Database Setup

# app/database.py
import os
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker
from dotenv import load_dotenv
from .models import Base

load_dotenv()

DATABASE_URL = os.getenv("DATABASE_URL", "sqlite+aiosqlite:///./resend_local.db")

# Only enable SQL logging in development — echo=True logs query values to stdout
_SQL_ECHO = os.getenv("DEBUG", "false").lower() == "true"
engine = create_async_engine(DATABASE_URL, echo=_SQL_ECHO)

AsyncSessionLocal = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)


async def init_db():
    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)


async def get_db():
    async with AsyncSessionLocal() as session:
        yield session

Note the echo flag — I learned the hard way that echo=True in production logs every SQL value (including email addresses) to stdout. Always tie it to a DEBUG environment variable.

Resend Service

This is the only file that talks to the Resend API. Everything else in the codebase uses the database directly.

# app/services/resend_service.py
import os
import resend
from dataclasses import dataclass
from typing import List
from dotenv import load_dotenv

load_dotenv()
resend.api_key = os.getenv("RESEND_API_KEY", "")


@dataclass
class EmailRecipient:
    email: str
    first_name: str = ""


# ── Domain management ─────────────────────────────────────────────────────────

def add_domain(domain_name: str) -> dict:
    """Register a domain with Resend. Returns DNS records for your customer."""
    return resend.Domains.create({"name": domain_name})


def verify_domain(domain_id: str) -> dict:
    """Ask Resend to check if DNS records have been added."""
    return resend.Domains.verify(domain_id)


def get_domain_status(domain_id: str) -> dict:
    """Poll verification status: not_started | pending | verified | failed"""
    return resend.Domains.get(domain_id)


# ── Email sending ─────────────────────────────────────────────────────────────

def send_single(from_domain: str, to_email: str, subject: str, html: str) -> dict:
    """Send one transactional email (confirmations, password resets, alerts)."""
    return resend.Emails.send({
        "from": f"hello@{from_domain}",
        "to": [to_email],
        "subject": subject,
        "html": html,
    })


def send_bulk(
    from_domain: str,
    recipients: List[EmailRecipient],
    subject: str,
    html_template: str
) -> List[dict]:
    """
    Send to any number of recipients by auto-splitting into batches of 100.
    Resend's batch endpoint limit is 100 emails per call.
    Replaces {{first_name}} per recipient — falls back to 'there' if no name.
    """
    results = []
    for i in range(0, len(recipients), 100):
        chunk = recipients[i:i + 100]
        emails = [
            {
                "from": f"hello@{from_domain}",
                "to": r.email,
                "subject": subject.replace("{{first_name}}", r.first_name or "there"),
                "html": html_template.replace("{{first_name}}", r.first_name or "there"),
            }
            for r in chunk
        ]
        results.append(resend.Batch.send(emails))
    return results

Keeping all Resend calls in one file pays off when writing tests — you only need to mock one module.

Domain Management

The domain setup is two steps: register (get DNS records), then verify (after your customer adds those records).

# app/routers/customers.py  (domain endpoints)

@router.post("/{customer_id}/domains", summary="Step 1 — Register domain with Resend")
async def add_domain(customer_id: str, body: AddDomainRequest, db: AsyncSession = Depends(get_db)):
    customer = await _get_customer_or_404(customer_id, db)

    try:
        resend_resp = resend_service.add_domain(body.domain_name)
    except Exception as e:
        raise HTTPException(status_code=400, detail=f"Resend error: {str(e)}")

    customer.domain_name = body.domain_name
    customer.resend_domain_id = resend_resp.get("id")
    customer.domain_verified = False
    await db.commit()

    return {
        "domain": body.domain_name,
        "resend_domain_id": resend_resp.get("id"),
        "dns_records": resend_resp.get("records", []),
        "next_step": f"Share dns_records with your customer, then call POST /customers/{customer_id}/domains/verify",
    }


@router.post("/{customer_id}/domains/verify", summary="Step 2 — Trigger verification")
async def verify_domain(customer_id: str, db: AsyncSession = Depends(get_db)):
    customer = await _get_customer_or_404(customer_id, db)
    if not customer.resend_domain_id:
        raise HTTPException(status_code=400, detail="No domain registered. Call /domains first.")

    resend_service.verify_domain(customer.resend_domain_id)
    status_resp = resend_service.get_domain_status(customer.resend_domain_id)
    is_verified = status_resp.get("status") == "verified"

    if is_verified:
        customer.domain_verified = True
        await db.commit()

    return {
        "domain": customer.domain_name,
        "verified": is_verified,
        "status": status_resp.get("status"),
        "message": "Domain verified. Emails can now be sent."
                   if is_verified else
                   "Not verified yet. DNS changes can take up to 48 hours.",
    }

DNS propagation is real. Even after a customer correctly adds their DNS records, verification can take up to 48 hours. Build a polling endpoint (GET /customers/{id}/domains/status) and have your frontend check it every 30–60 seconds rather than expecting instant success.

Contact and Segment Management

Contacts live entirely in your database. Nothing is sent to Resend when you add or update a contact — Resend only gets involved at send time.

Key points in the contact routes:

Duplicate guard — same email cannot be added twice under the same customer:

existing = await db.execute(
    select(Contact).where(
        and_(Contact.customer_id == customer_id, Contact.email == body.email)
    )
)
if existing.scalar_one_or_none():
    raise HTTPException(status_code=409, detail=f"Contact with email '{body.email}' already exists.")

Tag filtering — because JSON doesn't support array operators like PostgreSQL's @>, filtering by tag is done in Python after the DB query:

contacts_result = await db.execute(query)
contacts = contacts_result.scalars().all()

if body.tag:
    contacts = [c for c in contacts if c.tags and body.tag in c.tags]

This is fine at the scale of most SaaS apps. If you're dealing with millions of contacts, switch to PostgreSQL's JSONB with GIN indexes for this column.

Segments are named groups you manage explicitly. You create a segment, then add contact IDs to it:

POST /customers/{id}/segments          → create segment
POST /customers/{id}/segments/{sid}/contacts  → add contacts

Contacts added to a wrong customer's segment are silently skipped — no error, no leak.

Sending Emails

The send endpoint handles three targeting modes — all contacts, by tag, or by segment:

# app/routers/email.py

@router.post("/{customer_id}/send")
async def send_email(customer_id: str, body: SendEmailRequest, db: AsyncSession = Depends(get_db)):
    customer = await _get_verified_customer_or_error(customer_id, db)

    # ── Resolve target contacts ───────────────────────────────────────────────
    if body.segment_id:
        query = (
            select(Contact)
            .join(ContactSegment, Contact.id == ContactSegment.contact_id)
            .where(
                ContactSegment.segment_id == body.segment_id,
                Contact.customer_id == customer_id,
                Contact.is_subscribed == True,
            )
        )
    else:
        query = select(Contact).where(
            Contact.customer_id == customer_id,
            Contact.is_subscribed == True,
        )

    contacts_result = await db.execute(query)
    contacts = contacts_result.scalars().all()

    # Tag filter applied in Python (JSON column — no DB-level array operator)
    if body.tag and not body.segment_id:
        contacts = [c for c in contacts if c.tags and body.tag in c.tags]

    if not contacts:
        raise HTTPException(status_code=400, detail="No subscribed contacts match targeting criteria.")

    recipients = [EmailRecipient(email=c.email, first_name=c.first_name or "") for c in contacts]

    # ── Send (auto-batches every 100 recipients) ──────────────────────────────
    try:
        results = send_bulk(
            from_domain=customer.domain_name,
            recipients=recipients,
            subject=body.subject,
            html_template=body.html,
        )
    except Exception as e:
        raise HTTPException(status_code=502, detail=f"Resend delivery error: {str(e)}")

    # ── Record campaign history ───────────────────────────────────────────────
    targeting = {}
    if body.segment_id:
        targeting = {"segment_id": body.segment_id}
    elif body.tag:
        targeting = {"tag": body.tag}

    campaign = Campaign(
        customer_id=customer_id,
        subject=body.subject,
        sent_to_count=len(recipients),
        from_address=f"hello@{customer.domain_name}",
        targeting=targeting,
        status="sent",
    )
    db.add(campaign)
    await db.commit()

    return {
        "success": True,
        "campaign_id": campaign.id,
        "sent_to": len(recipients),
        "from": f"hello@{customer.domain_name}",
        "batches_used": len(results),
    }

The segment_id takes priority if both segment_id and tag are provided — one clear rule, no ambiguity.

Campaign History

Every send automatically creates a Campaign record. The campaign routes let you retrieve and clean up that history:

# GET /customers/{id}/campaigns       — list all, newest first
# GET /customers/{id}/campaigns/{cid} — single campaign
# DELETE /customers/{id}/campaigns/{cid} — remove record (does NOT unsend emails)

The delete endpoint is worth a comment — it removes the database record only. Emails already sent cannot be recalled. This is useful for cleaning up test sends during development.

Handling Resend Webhooks

Resend uses Svix to deliver webhooks. Every event POST includes three signature headers you verify with HMAC-SHA256.

# app/routers/webhooks.py
import os, hmac, hashlib, base64, logging
from fastapi import APIRouter, Request, HTTPException, Header
from typing import Optional

router = APIRouter(prefix="/webhooks", tags=["Webhooks"])
logger = logging.getLogger(__name__)


def _get_secret() -> str:
    """Read per-request so runtime environment changes are picked up."""
    return os.getenv("WEBHOOK_SECRET", "")


def _verify_svix_signature(
    payload: bytes, svix_id: str, svix_timestamp: str, svix_signature: str, secret: str
) -> bool:
    if secret.startswith("whsec_"):
        secret_bytes = base64.b64decode(secret[6:])
    else:
        secret_bytes = secret.encode()

    signed_content = f"{svix_id}.{svix_timestamp}.".encode() + payload
    expected = base64.b64encode(
        hmac.new(secret_bytes, signed_content, hashlib.sha256).digest()
    ).decode()

    for sig in svix_signature.split(" "):
        if sig.startswith("v1,") and hmac.compare_digest(expected, sig[3:]):
            return True
    return False


@router.post("/resend")
async def handle_resend_webhook(
    request: Request,
    svix_id: Optional[str] = Header(None, alias="svix-id"),
    svix_timestamp: Optional[str] = Header(None, alias="svix-timestamp"),
    svix_signature: Optional[str] = Header(None, alias="svix-signature"),
):
    payload = await request.body()
    secret = _get_secret()

    if secret:
        if not all([svix_id, svix_timestamp, svix_signature]):
            raise HTTPException(status_code=400, detail="Missing svix-* signature headers.")
        if not _verify_svix_signature(payload, svix_id, svix_timestamp, svix_signature, secret):
            raise HTTPException(status_code=401, detail="Webhook signature verification failed.")

    event = await request.json()
    event_type = event.get("type", "")
    data = event.get("data", {})

    if event_type == "email.bounced":
        to = data.get("to", [])
        logger.info(f"Hard bounce for {to} — marking unsubscribed")
        # TODO: set Contact.is_subscribed = False for each address in `to`

    elif event_type == "email.complained":
        to = data.get("to", [])
        logger.info(f"Spam complaint from {to} — unsubscribing immediately")
        # TODO: set Contact.is_subscribed = False

    # Always return 200 — anything else causes Resend to retry for 24 hours
    return {"received": True, "type": event_type}

Three things worth noting here:

1. Read the secret per-request, not at import time. If you read WEBHOOK_SECRET as a module-level constant, changes to the environment variable after startup have no effect. Reading it per-request inside _get_secret() avoids this.

2. compare_digest prevents timing attacks. Using == to compare signatures leaks information through response time differences. hmac.compare_digest takes constant time regardless of where a mismatch occurs.

3. Always return 200. Resend retries webhook delivery on any non-2xx response. Your handler should be idempotent — processing the same event twice should have no side effects.

Local webhook testing: Use npx svix-cli listen http://localhost:8000/webhooks/resend to get a public forwarding URL. Register that URL in your Resend dashboard, copy the signing secret into .env, and real webhook events will reach your local server.

Testing Without a Real Domain

This was the part I found most valuable to figure out. You can write a complete test suite for this entire service — all 88 tests — without a verified domain, without spending any Resend API credits, and without setting up a webhook endpoint.

The approach: mock the one module that calls Resend, and use an in-memory SQLite database for everything else.

# tests/conftest.py
import pytest_asyncio
from unittest.mock import patch, MagicMock
from httpx import AsyncClient, ASGITransport
from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker, AsyncSession
from app.main import app
from app.database import get_db
from app.models import Base

TEST_DATABASE_URL = "sqlite+aiosqlite:///:memory:"


@pytest_asyncio.fixture(scope="function")
async def db_session():
    engine = create_async_engine(TEST_DATABASE_URL, connect_args={"check_same_thread": False})
    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)
    SessionLocal = async_sessionmaker(engine, expire_on_commit=False)
    async with SessionLocal() as session:
        yield session
    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.drop_all)
    await engine.dispose()


@pytest_asyncio.fixture(scope="function")
async def client(db_session: AsyncSession):
    async def override_get_db():
        yield db_session

    app.dependency_overrides[get_db] = override_get_db

    with (
        patch("app.routers.customers.resend_service.add_domain",
              MagicMock(return_value={"id": "dom_test", "status": "not_started", "records": []})),
        patch("app.routers.customers.resend_service.verify_domain", MagicMock()),
        patch("app.routers.customers.resend_service.get_domain_status",
              MagicMock(return_value={"status": "verified"})),
        patch("app.routers.email.send_single", MagicMock(return_value={"id": "email_abc"})),
        patch("app.routers.email.send_bulk",   MagicMock(return_value=[{"data": []}])),
    ):
        async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
            yield ac

    app.dependency_overrides.clear()

With this in place, a test that verifies the full send flow looks like this:

# tests/test_email.py

async def test_send_filtered_by_tag(client):
    # Create customer with verified domain
    c = await client.post("/customers/", json={"name": "Acme"})
    cid = c.json()["id"]
    await client.post(f"/customers/{cid}/domains", json={"domain_name": "acme.com"})
    await client.post(f"/customers/{cid}/domains/verify")

    # Add contacts with different tags
    await client.post(f"/customers/{cid}/contacts",
                      json={"email": "premium@acme.com", "tags": ["premium"]})
    await client.post(f"/customers/{cid}/contacts",
                      json={"email": "free@acme.com", "tags": ["free"]})

    # Send only to premium tag — should reach 1 contact
    r = await client.post(f"/customers/{cid}/send", json={
        "subject": "VIP offer",
        "html": "<p>Exclusive for you</p>",
        "tag": "premium",
    })

    assert r.status_code == 200
    assert r.json()["sent_to"] == 1
    assert "campaign_id" in r.json()  # campaign was recorded

The test runs in milliseconds with no network calls. The mock domain verification always returns "verified" so you can test every send scenario without touching a real Resend account.

For the webhook tests, you generate valid Svix signatures in the test itself:

def _make_svix_headers(payload: bytes, secret: str) -> dict:
    if secret.startswith("whsec_"):
        secret_bytes = base64.b64decode(secret[6:])
    else:
        secret_bytes = secret.encode()

    svix_id = "msg_test01"
    svix_timestamp = "1713000000"
    signed_content = f"{svix_id}.{svix_timestamp}.".encode() + payload
    digest = hmac.new(secret_bytes, signed_content, hashlib.sha256).digest()
    sig = base64.b64encode(digest).decode()

    return {
        "svix-id": svix_id,
        "svix-timestamp": svix_timestamp,
        "svix-signature": f"v1,{sig}",
    }

Call this in your test with a known secret, patch _get_secret() to return that secret, and you can fully test both the valid and tampered-signature paths — no real Resend webhook needed.

On top of the unit tests, there are 16 Playwright end-to-end tests that spin up a real uvicorn server and hit it over actual HTTP. This catches issues the httpx tests miss: middleware ordering, serialisation edge cases, and real TCP behaviour. The setup is in tests/e2e/conftest.py — the same Resend mocks apply, just applied before the server starts.

App Entry Point

# app/main.py
from contextlib import asynccontextmanager
from fastapi import FastAPI
from .database import init_db
from .routers import customers, contacts, email, webhooks, campaigns


@asynccontextmanager
async def lifespan(app: FastAPI):
    await init_db()   # creates tables on startup
    yield


app = FastAPI(
    title="Multi-Tenant Email Service — Resend + FastAPI",
    lifespan=lifespan,
)

app.include_router(customers.router)
app.include_router(contacts.router)
app.include_router(email.router)
app.include_router(campaigns.router)
app.include_router(webhooks.router)

Using lifespan instead of the deprecated @app.on_event("startup") — FastAPI has recommended this pattern since version 0.93.

Security Considerations

A few things I'd flag before putting this in front of real traffic:

There is no authentication on any endpoint. This is intentional for the article — adding auth is a separate concern and would double the length. In production, add at minimum a shared X-API-Key header check, or preferably per-customer bearer tokens. Without this, anyone who can reach your server can read and delete all customer data.

Rate limit the /send endpoints. An unprotected send endpoint is an open relay for spam. Add slowapi or similar middleware before exposing this publicly.

Set WEBHOOK_SECRET in production. Without it, anyone can POST to /webhooks/resend and your handler will process it. The startup warning in the logs is a reminder, not a substitute for setting the variable.

Keep DEBUG=false in production. With DEBUG=true, every SQL query — including the values of email addresses — goes to stdout.

The Complete Flow in Practice

1. Onboard a customer
   POST /customers/
   POST /customers/{id}/domains  → get DNS records, give to customer

2. Wait for DNS propagation (up to 48 hours)
   GET /customers/{id}/domains/status  → poll until "verified"

3. Add contacts
   POST /customers/{id}/contacts  → stored in your DB, nothing goes to Resend

4. Create segments (optional)
   POST /customers/{id}/segments
   POST /customers/{id}/segments/{sid}/contacts

5. Send a campaign
   POST /customers/{id}/send
   {"subject": "Hello {{first_name}}!", "html": "...", "tag": "premium"}
   → fetches contacts from DB, sends via Resend in batches of 100
   → records a Campaign row automatically

6. Receive delivery events
   POST /webhooks/resend  → auto-unsubscribes bounces and complaints

What I'd Do Differently

1. Don't rely on Resend's Audiences for any production filtering. The feature exists in the dashboard, but the API has no filtering endpoint for Segments. If you need any filtering by attribute — tag, plan, activity date — store it yourself.

2. Build DNS verification polling from day one. Customers expect to see something updating on screen. A simple GET /customers/{id}/domains/status endpoint that your frontend polls every 30 seconds is much better UX than a spinner that does nothing.

3. Webhook endpoint must be live before you start integration testing. Resend validates the URL you register. Set it up first — even if the handler just returns {"received": true} — before testing delivery events end-to-end.

4. Unsubscribe handling is not optional. Resend (like every email provider) monitors your bounce rate. Too many bounces and your account gets flagged. Build the auto-unsubscribe logic in from day one, not as a follow-up task.

5. Use aiosqlite locally, asyncpg in production. Switching between them is one line in .env — no code changes. It saves a lot of setup time during development.

Summary

Resend is an excellent email delivery service — fast, reliable, and the API is genuinely clean. But it's a sending engine, not a CRM. If you're building anything multi-tenant or anything that needs contact segmentation, own that layer yourself.

The pattern in this article gives you:

Per-customer domain isolation with full DNS verification flow
Complete contact and segment management in your own database
Scalable batch sending with {{first_name}} personalisation
Campaign history recorded on every send
Delivery tracking and auto-unsubscribe via webhooks
A full test suite that runs offline with no API credits

The full working code is on GitHub: https://github.com/srinivaspavuluri/resend-fastapi

Ran into a different edge case with Resend, or built something on top of this pattern? Drop it in the comments.