Bounce Handling and Suppression Lists: The Deliverability Foundation Most Email APIs Skip
Every developer worries about the happy path: did my API call return 200? Almost nobody asks the question that actually determines whether emails reach the inbox: what happens when the address is dead?
A dead address isn't a one-time error. It's a signal. Send to enough dead addresses and inbox providers start treating every email you send as suspect. Your domain reputation tanks, and suddenly the emails to real, valid addresses start landing in spam.
This is the deliverability foundation — and it's the part most developers (and many email APIs) skip entirely.
Hard bounce vs soft bounce: not the same problem
A bounce is what happens when an inbox provider refuses to accept your email. But "refused" means different things, and treating them all the same is the first mistake.
Hard bounces are permanent. The address doesn't exist, the domain has no mail server, or the mailbox was disabled. Example: [email protected]. There is no retry that fixes a hard bounce. Sending again is worse than pointless — it actively damages your reputation, because it tells the provider "this sender doesn't clean their list."
Soft bounces are temporary. The recipient's inbox is full, the server is down, or the message is too large. Soft bounces deserve a retry — but a bounded retry. If an address soft-bounces on every attempt for 72 hours, it should be treated as a hard bounce.
The rule that matters: hard bounces suppress immediately, soft bounces suppress after N failures. An email API that doesn't distinguish them is quietly poisoning your domain.
Why bounces matter more than you think
Inbox providers (Gmail, Yahoo, Outlook, and every major ISP in Indonesia) build a reputation score for every sending domain. The inputs are straightforward:
- Bounce rate — what percentage of your sends come back rejected
- Complaint rate — how often recipients hit "mark as spam"
- Authentication — are you sending with valid SPF, DKIM, and DMARC
- Engagement — do recipients open, reply, or leave your mail unread
Bounce rate is the fastest way to destroy the first three. A domain sending to a 10% bounce rate will see deliverability collapse within days, even if its authentication is perfect.
Here's the part that trips people up: the damage accumulates before you notice. Transactional email is often triggered by code — a signup, a password reset, a payment confirmation. If a typo in a form or an old imported list puts bad addresses into that flow, the bounces pile up silently while you watch your "200 OK" responses roll in.
Suppression lists: the mechanism that protects you
A suppression list is the set of addresses you (and your email provider) have agreed never to send to again. Three things belong on it:
- Hard-bounced addresses — dead mailboxes, nonexistent domains.
- Spam complaints — recipients who explicitly marked your mail as spam. (Providers report these back through feedback loops.)
- Explicit unsubscribes — for anything with a marketing component, even if it's "just" a notification.
The suppression check has to happen at two points, and this is where cheap email APIs cut corners:
- At enqueue — before the message ever enters the queue, check the recipient against the list and drop it silently (or return a specific error code).
- At send — check again right before the actual send, because the list can change between enqueue and delivery.
Skip either check and you'll leak suppressed addresses through. One leaked address per thousand sends is enough to move your bounce rate.
Retention matters too. Best practice is to hold suppressed addresses for a meaningful window — 90 days is common — because a hard bounce today is overwhelmingly likely to be a hard bounce next month. Re-sending to a long-dead address a month later is how a "one bad day" becomes a permanent reputation scar.
Feedback loops: the complaint you don't see
When a recipient hits "report spam," they don't email you. The inbox provider records the complaint and reports it back to your sending infrastructure through a feedback loop (FBL).
A competent email API subscribes to FBLs automatically and converts complaints into suppression-list entries. A lazy one ignores them, and you keep happily sending to someone who just told Gmail "I don't want this."
The complaint rate that gets you flagged is astonishingly low — Gmail and Yahoo start side-eyeing domains at a fraction of a percent. It is far cheaper to suppress one angry recipient than to rehabilitate a domain flagged for spam.
What to demand from your email API
When you're picking a transactional email API, bounces and suppression are not a "nice to have" feature. They are the difference between email that arrives and email that evaporates. Ask these questions:
- Do you distinguish hard and soft bounces? If the answer is "all bounces are bounces," keep looking.
- Where is the suppression check performed? It must be at enqueue and at send. One check is not enough.
- How long are suppressed addresses retained? Short retention means old bad addresses leak back in.
- Do you process feedback loops automatically? Complaints must become suppressions without you lifting a finger.
- Can I see my bounce and complaint rates? If you can't measure it, you can't fix it.
Why this matters doubly for Indonesian builders
Indonesian developers face a specific version of this problem. International email APIs price in USD, bill by credit card, and treat deliverability as something you opt into — with documentation in English and support that sleeps when you're awake.
But the deliverability rules are global. Gmail does not care whether your startup is in Jakarta or San Francisco. A dead address is a dead address, and the bounce that kills your domain reputation in IDR costs exactly as much as one in USD.
This is why bounce handling and suppression must be automatic, not a feature you configure later. A transactional email API built for Indonesian developers should treat suppression as a core invariant — enforced at enqueue, enforced again at send, with 90-day retention and automatic feedback-loop processing — so that you get global-standard deliverability without having to become an email infrastructure expert first.
The checklist
Before you send your next transactional email, confirm:
- [ ] My provider distinguishes hard and soft bounces
- [ ] Hard bounces are suppressed immediately
- [ ] Soft bounces retry a bounded number of times, then suppress
- [ ] Suppression is checked at enqueue and at send
- [ ] Spam complaints are processed automatically via feedback loops
- [ ] Suppressed addresses are retained at least 90 days
- [ ] I can see my bounce rate and complaint rate in a dashboard
Skip any of these and you're not running email infrastructure — you're running an experiment on your domain's reputation.
MailAnvil treats suppression as a core invariant. Hard/soft bounce distinction, suppression checked at enqueue and at send, automatic feedback-loop processing, and 90-day retention — built in, so your domain reputation is protected by default. Edge delivery via Cloudflare Workers, IDR pricing, QRIS & GoPay.