Skip to content
← Back to blog

Cleaning a Suppression List Before It Costs You a Customer

7 min read
emaildeliverabilityguide

A customer writes in: "I still haven't got the receipt for invoice 2291. Can you resend it?"

You look. Your app says the email was sent — there is a row in your own database, a timestamp, a green checkmark in the admin panel. You resend it anyway, because that costs nothing. She writes back an hour later: still nothing. You check her spam folder over a screen share. Empty. You send from your personal Gmail to make sure her address works. It arrives in four seconds.

So the address is fine, your app thinks it sent, and the mail is not arriving. At this point most people start suspecting DNS, and start reading about authentication records, and lose an afternoon. The actual answer is one lookup away in a list nobody remembers exists: her address is on your suppression list. It has been since July, when her company's mail server spent four hours misconfigured and rejected everything with a 550. A 550 is a permanent failure — that is what the number means — so it was recorded as a hard bounce and her address was blocked. The server was fixed by lunchtime. Your suppression list was not.

Nothing in your product will ever tell you this. The send did not error. It was accepted, evaluated, and dropped on purpose, by a mechanism you installed to protect yourself.

The mechanism is doing its job

Start from the position that the suppression list is right, because it is.

Email providers score you on the fraction of your mail that bounces and the fraction that gets marked as spam. Cross their thresholds and there is no warning — they throttle, then filter, then silently discard, and recovery takes weeks. Every serious sending platform therefore keeps a list of addresses it refuses to send to: hard bounces, spam complaints, unsubscribes, and anything you blocked by hand. A send to an address on that list is recorded as blocked and never handed to the provider.

That list is what stands between one bad import and a domain reputation you cannot repair. So the reflex — this is causing problems, let me turn it off — is wrong, and a platform that lets you disable suppression wholesale has a bug. The list is not the problem. The problem is that it is write-mostly: entries arrive constantly and automatically, from provider signals you never see, and nothing takes them off. A protective mechanism with an unbounded, invisible accumulation of state will eventually be wrong about someone, quietly.

None of this is about authentication, incidentally. If your mail is landing in spam folders rather than nowhere at all, that is a different problem and it is covered in email deliverability in plain English. Suppression is what happens before any of that runs — the send never leaves the building.

Four reasons, and they are not the same kind of thing

Every entry has a reason, and treating them all as equivalent is what makes the list dangerous. Helmdesk records four, and most platforms record something close:

  • Bounce. The receiving server permanently rejected the message. Sometimes the mailbox truly does not exist — a typo at signup, which is the benign case, since that address was never going to work. Sometimes a mail server was having a bad day, a corporate filter answered 5xx when it meant 4xx, or a full mailbox got reported as permanent rather than "try later". The signal is ambiguous, and it produces most of the bad entries.
  • Complaint. Someone clicked "this is spam". This is the most reliable entry on the list and the one you should touch least. Whatever your view of whether the mail was spam, that customer told a mail provider it was, and mailing them again is how you convert one complaint into a reputation problem.
  • Unsubscribe. They asked to stop. This is a request, not a diagnosis — and the important nuance is that it may not have been meant to cover everything. Somebody who unsubscribed from a product-update newsletter usually still expects their receipts.
  • Manual. Somebody on your team added it, for a reason that made sense at the time and was written down nowhere. Six months later it is an address nobody can explain.

Two of those — complaint and unsubscribe — represent a decision a human made. Leave them alone. The other two are the ones worth auditing, because a bounce is a machine's guess and a manual entry is a colleague's memory.

The audit worth running every quarter

This is a fifteen-minute job, four times a year, and it is one of the highest-value fifteen minutes in your ops calendar.

const { suppressions } = await helmdesk.emails.suppressions.list({ reason: 'bounce' })

const questionable = suppressions.filter((s) => {
  const daysOld = (Date.now() - Date.parse(s.createdAt)) / 86_400_000
  return daysOld > 90 && !s.email.match(/^[^@]*(test|noreply|admin)@/)
})

The tool behind that is list_suppressions, and the shape of the review is what matters more than the code. For each bounce entry older than a quarter, ask two questions: is this a real person, and did it bounce once or repeatedly? A single bounce ninety days ago against an address that belongs to a paying customer is a candidate for removal. Twelve bounces against jsmith@nonexistent-domain.example is the system working.

Cross-reference against your customer directory, not against your instincts. An address that appears on the suppression list and has an active subscription is the exact intersection you are looking for, and it is usually a very short list — two or three addresses, each one a person currently unable to receive anything you send. remove_suppression clears one, and the next send to that address goes out normally.

Manual entries deserve the same pass with a different question: who added this, and is that reason still true? If nobody can answer, remove it and let the provider signals decide — it will go straight back on if it was right.

Set expectations properly. This audit finds something almost every time, and what it finds is small: two addresses, not two hundred. Two is enough — those are two people who currently think you ignore them.

The lookup that almost nobody does

Here is the part that changes day-to-day support, and it costs one habit rather than one project.

When a customer says "I never got the email", the very first thing to check is your own email log, not your app's database. Your app knows it asked for an email to be sent. The email log knows what happened next: queued, sent, delivered, opened, bounced — or blocked, with a reason attached that says the recipient is suppressed. list_email_sends filtered by that address answers the question in seconds; get_email_send gives you the full event timeline for one message when you want to know exactly where it stopped.

Almost nobody looks. The instinct is to resend — resend_email is right there and it feels like doing something — but a resend to a suppressed address is blocked exactly like the first, and now you have two identical non-events and a customer told twice that it is on its way.

Make it a rule: check the log before you resend. That one habit converts a category of support ticket that normally ends in a shrug into a category that ends in an answer, which is the most improvement you will ever get from a fifteen-second query.

The bottom line

A suppression list is a fence you build to keep your sending reputation alive, and fences do not know who is on which side. Bounces and manual blocks accumulate silently, nothing removes them, and eventually one of them is standing between a paying customer and the receipt they are politely asking for.

Do not tear the fence down. Walk it once a quarter, and look at the log before you tell anyone the email is on its way — because right now, the honest answer to "why didn't my customer get the email" is sitting in a table you have never opened.

Find out why the email never arrived

A per-project email log with the full event timeline, and a suppression list you can read, filter, and clean before it silences a customer.