# Suppressions · Stop mailing the addresses that hurt you

Recipient protection

Example record

Hard bounces suppress all email. Complaints suppress non-transactional email. Unsubscribe preferences are stored separately.

## The single biggest lever on your reputation.

Suppression is built into the [Bird Email API](/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.

- **01** Automatic on bounce + complaint. Hard bounces and spam complaints create suppression records automatically. Unsubscribes appear in Preferences.
- **02** Reversible. Investigate the cause before removing a suppression. Other blocking records and opt-out preferences remain in effect.
- **03** Manual entries. Add addresses yourself: a known-bad list you're importing from another provider, say.
- **04** 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.
- **05** 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**

```bash
# 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
```

## 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](/docs/guides/email/suppressions), and how it fits the bigger picture in the [deliverability guide](/docs/guides/email/deliverability).

## Questions 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

- [Audiences](/email-api/features/audiences): Your contacts and the audiences you target from a broadcast.
- [Deliverability](/email-api/features/deliverability): Authentication, IP warmup, suppression, and per-provider visibility.
- [Analytics](/email-api/features/analytics): Delivery and engagement metrics per mailbox provider, domain, and IP.
- [Email API overview](/email-api): The full Email API: sending, deliverability, IPs, suppression, analytics, and broadcasts.

## Scale without  losing control.

Organize teams in workspaces, control API access, and trace changes through audit logs.

Harbor Organization
Workspaces Production Sandbox

### Delivery agent

API key · Customer operations team
Active
Permissions Access
Email Read & write
SMS Read & write
WhatsApp Read Read & write
AL Alex Lee Admin  Permissions updated

### Audit log

Production
 API key updated Alex Lee · 09:42:18 UTC

Workspace
Production

Resource
Delivery agent

WhatsApp
Read Read & write

Succeeded

 [Workspaces](/docs/guides/workspaces)[Team roles](/docs/guides/users-teams-roles)[API authentication](/docs/guides/authentication)
[Explore Enterprise](/enterprise)

## Start with Email. Build across channels with Bird.

[Get started](/dashboard/signup?returnTo=%2Fdashboard%2Fw%2Femail) · [Contact Sales](/demo?product=email)

[Email](/email-api) · [SMS](/sms-api) · [WhatsApp](/whatsapp-api) · [Apple Messages](/apple-messages-api) · [Voice](/voice-api)



## Related resources

- [What happens when someone opts out](/learn/email/what-happens-when-someone-opts-out) (video)
- [What is one-click unsubscribe, and how do I implement List-Unsubscribe?](/explained/deliverability/what-is-one-click-unsubscribe) (answer)
- [Operate messaging reliably](/learn/paths/reliability) (course)

[Get an implementation brief](/learn/workspace?topic=email-suppression)