Understand why a send stopped.
Read the suppression reason and applicable category. A manual restriction, a complaint and a bounce can have different origins; preserve the information needed to review the decision.
Read suppression behavior ↗EmailSuppressions
Email suppressions.
Remember what matters.
Keep delivery restrictions with the sending decision. Understand why a recipient is suppressed and avoid repeating a known ineligible send.
A stopped send should have a clear reason.
Understand why an address is excluded before the next send. Review its history alongside the message category and the customer’s preferences.
HISTORY / alex@example.com
- Campaign membership
The address belongs to the selected example audience.
- Restriction recorded
A bounce, complaint or manual migration record carries its own reason and scope.
- Eligibility evaluated
Customer preference and suppression are evaluated separately.
{
"recipient": "alex@example.com",
"reason": "hard_bounce",
"applies_to": "all",
"category": "marketing",
"preference": "allowed",
"replayed_decision": false
}ELIGIBILITY / CURRENT SELECTIONRead suppression scope and removal ↗
Inspect the record.Exclude the recipient.This record allows the category.
No current decision. Trace this reason, category and preference; changing inputs clears the previous result.
Customer policy excludes this recipient even if this suppression record allows the category.
The scope is unrecognized. Keep the recipient excluded and inspect the documented policy; unknown scope is not sending permission.
The recorded restriction blocks this category. Audience membership and a repeated event do not erase it.
This complaint record alone does not block the transactional example. Other suppressions, preferences and account policy still need checking before a send.
Repeated evaluation: the same restriction remains authoritative. No new record or send was created.
Companies that trust Bird across their communications.
Read Bird customer storiesSending policy with a clear history.
Carry valid restrictions forward.
A migration needs recipient restrictions as well as addresses. Keep contact permission and unsubscribe preferences separate, and investigate incomplete exports before moving a cohort.
Prepare the migration ↗The single biggest lever on your reputation.
Suppression is built into the Bird Email API. Hard-bounce records stop mail to invalid addresses, and complaint records stop non-transactional mail. You can inspect the reason and originating message to understand why a recipient was rejected.
Five ways suppression protects you.
Automatic, reversible, and queryable.
Automatic on bounce + complaint.
Hard bounces and spam complaints create suppression records automatically. Unsubscribes appear in Preferences.
Reversible.
Investigate the cause before removing a suppression. Other blocking records and opt-out preferences remain in effect.
Manual entries.
Add addresses yourself: a known-bad list you're importing from another provider, say.
Queryable via API.
List the whole thing, filter by address or reason, add an entry, or delete one by its record id, so your own systems stay in sync.
Category-aware checks.
Hard-bounce and manual suppressions block all categories. Complaints block non-transactional mail. A recipient’s preferences are checked separately.
Automatic by default, yours to control.
You never have to touch the list for it to work; bounces and complaints suppress on their own. When you do need to, the whole list is an API: add an address you already know is bad, filter by address or reason, or delete a record to reinstate a recipient that recovered. The bird CLI covers the reads and the removals, and an agent reaches the same two over MCP.
suppressions.sh
bird CLI
# Look up why an address is on the list.
$ bird email suppressions list --email ada@example.com \
| jq -c '.data[] | {id, reason, applies_to}'
{"id":"sup_01krdgeqcxet5s7t44vh8rt9mg","reason":"hard_bounce",
"applies_to":"all"}
# Reinstate one that recovered, by record id.
$ bird email suppressions remove sup_01krdgeqcxet5s7t44vh8rt9mg --yes
Look up a suppression with CLI or MCP before changing it. Review the reason and the recipient’s consent before deciding whether to resume sending.
Three suppression reasons. Separate preferences.
Hard bounces and manual entries block all mail. Complaints block non-transactional mail. An unsubscribe creates a separate preference; removing a suppression does not erase that preference.
| Reason | Triggered by | Blocks |
|---|---|---|
| hard_bounce | a permanent bounce | all mail (transactional + marketing) |
| complaint | a spam complaint | marketing only |
| manual | you, via API or dashboard | all mail (transactional + marketing) |
Go deeper in the docs.
Read how automatic and manual suppression work in the suppressions guide, and how it fits the bigger picture in the deliverability guide.
Put it into practice.
Continue with the documentation, guides and examples for this topic. Resources are in English.
Watch the guideWhat happens when someone opts outUnderstand the conceptWhat is one-click unsubscribe, and how do I implement List-Unsubscribe?Follow the learning pathOperate messaging reliably
Get an implementation briefQuestions about email suppressions
Which recipients are suppressed automatically?
Hard bounces create suppressions for all mail; complaints create suppressions for non-transactional mail. Manual suppressions block all categories. Soft bounces and deferrals do not create permanent recipient suppressions.
Is an unsubscribe a suppression?
An unsubscribe records the recipient’s preference on the Preferences tab. It is separate from the suppression list. Both are checked when deciding whether to deliver, and deleting a contact does not erase its opt-out.
Can I remove or test a suppression?
You can remove a suppression through the dashboard or API after investigating its cause. Removing one does not remove other blocking records or opt-out preferences. The suppressed@messagebird.dev sandbox address lets you test a rejected recipient without changing your list.
Protect the next send
Manage restrictions through change
Follow an opt-out, complaint and imported record without losing their meaning.
Audiences
Your contacts and the audiences you target from a broadcast.
Deliverability
Authentication, IP warmup, suppression, and per-provider visibility.
Analytics
Delivery and engagement metrics per mailbox provider, domain, and IP.
Email API overview
The full Email API: sending, deliverability, IPs, suppression, analytics, and broadcasts.
Talk to our email team
Make recipient preferences part of your sending.
Discuss opt-outs, suppression imports and application-level controls. We’ll help you plan how recipient preferences move with your email.
Create your account, then review or import the recipients you need to exclude.