Email deliverability 101 for developers
Deliverability is the part of email infrastructure most developers ignore until something goes wrong. You integrate Resend or SES, send emails, and assume they arrive. Then a user tells you they never got your email. You check Resend and it says delivered. It went to spam.
Deliverability is the gap between "the mail server accepted the email" and "the email arrived in the inbox." Closing that gap comes down to three things: authentication, sending behaviour, and list hygiene. None of it is complicated, but all of it matters.
Authentication: SPF, DKIM, and DMARC
Mailbox providers start every decision with one question: is this email really from who it says it is? Three DNS records answer it, and you want all three.
SPF
Sender Policy Framework is a TXT record listing which servers may send mail for your domain. When Gmail receives a message from yourapp.com, it checks whether the sending server is on that list. Your provider tells you exactly which include: to add.
send.yourapp.com. TXT "v=spf1 include:amazonses.com ~all"A domain can have only one SPF record. If you send through Google Workspace and Resend from the same domain, both includes go in that one record. SPF also allows at most ten DNS lookups; nest too many includes and it fails without telling you.
DKIM
DomainKeys Identified Mail signs every message with a private key, and the matching public key lives in your DNS. The receiver verifies the signature, which proves the message wasn't altered in transit and was authorised by the domain owner. Your provider generates the key pair; you publish the public half as a TXT or CNAME record.
DMARC
DMARC ties the two together. It tells receivers what to do when a message fails SPF and DKIM alignment, and where to send reports about it. Start in monitoring mode:
_dmarc.yourapp.com. TXT "v=DMARC1; p=none; rua=mailto:dmarc@yourapp.com"Once the reports show your legitimate mail passing, tighten the policy to p=quarantine, then p=reject. Gmail and Yahoo require a DMARC record from anyone sending more than 5,000 messages a day to their users, and having one helps well below that threshold.
Check your setup
- Run
dig TXT send.yourapp.comanddig TXT _dmarc.yourapp.comto confirm the records resolve. - Send a test to a Gmail address, open it, and choose Show original. You want
PASSnext to SPF, DKIM, and DMARC. - Your provider's dashboard should mark every record as verified. Resend shows this per domain.
Sender reputation
Authentication proves who you are. Sender reputation decides whether anyone wants to hear from you. Mailbox providers score your sending domain and the IPs you send from, based on how recipients react to your mail.
The signals they watch most closely:
- Spam complaints. Every click on "Report spam." Google's guidance is to stay under 0.1% and never reach 0.3%.
- Bounce rate. Sending to addresses that don't exist looks like a stale or purchased list.
- Engagement. Opens, replies, rescuing mail from spam, and deleting without reading all count.
- Consistency. A sudden spike in volume from a domain that usually sends very little.
The fastest ways to damage it: sending to people who unsubscribed, emailing a list you haven't touched in a year, and sending one large blast from a brand-new domain.
Google Postmaster Tools is free and shows your spam rate and domain reputation once you send enough volume to Gmail addresses. Set it up early so you have a baseline before anything goes wrong.
List hygiene
The easiest reputation win is not sending mail that will bounce or annoy.
Hard vs soft bounces
| Type | What it means | What to do |
|---|---|---|
| Hard bounce | The address doesn't exist, or the domain permanently rejects mail | Suppress immediately and never send to it again |
| Soft bounce | Temporary: mailbox full, server down, message too large | Retry later; suppress after repeated failures |
Bounces reach you through your provider's webhooks. If nothing in your app is listening, you'll keep sending to dead addresses indefinitely.
Why suppression lists matter
A suppression list is every address you must never email again: hard bounces, spam complaints, and unsubscribes. It has to be checked on every send, across every campaign, not only the one where the person opted out. Most deliverability problems in small apps trace back to a script that didn't check it.
In BroadcastMail, unsubscribes, hard bounces, and complaints are added to your suppression list automatically and excluded from every future campaign.
Warming up a new domain
A domain with no history has no reputation, and providers treat unknown senders with caution. Send 10,000 emails on day one and a large share will be throttled or filtered.
Ramp up over two to four weeks, starting with your most engaged users:
- Week 1: a few hundred a day, to users who logged in recently.
- Week 2: roughly double the daily volume, as long as bounces and complaints stay low.
- Week 3 onward: expand to the rest of the list, keeping volume steady rather than spiky.
Send product email from a subdomain such as mail.yourapp.com. If a campaign goes badly, the damage stays away from the domain your transactional email and team inboxes depend on.
When emails land in spam
Work through these in order. Most cases are resolved by the first two.
- Check authentication. Open the headers (Show original in Gmail). Any SPF, DKIM, or DMARC failure is the first thing to fix.
- Check the list. Did this send include old, unengaged, or imported addresses? Look at the campaign's bounce rate.
- Check the content. Link shorteners, a single large image with little text, and link text that doesn't match its URL all raise flags.
- Check the From address. It should match your authenticated domain and stay the same from campaign to campaign.
- Slow down. Cut volume and send only to recently active users for a week while reputation recovers.
Deliverability is never finished, but it's mostly unglamorous: authenticate once, respect opt-outs, keep the list clean, and grow volume gradually.
Email your Supabase users today
Connect your project and send your first campaign in about five minutes. Free up to 500 recipients a month.