Suppressions

Stop mailing the addresses that hurt you.

Set up in:

Every bounce, complaint, and unsubscribe automatically adds the recipient to your suppression list, so you don't mail them again. Suppression is reversible, queryable through the API, and applies across transactional and marketing sends.

welcome.tsx

200 · 1.2s

import { BirdClient } from "@messagebird/sdk";
import { render } from "@react-email/render";
import { WelcomeEmail } from "./emails/welcome";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

const { data, error } = await bird.email.send({
  from:    "Bird <hello@bird.com>",
  to:      ["ada@example.com"],
  subject: "Your invite is ready",
  html:    await render(<WelcomeEmail name="Ada" />),
}).safe();

if (error) throw error;
console.log(data.id);
// → "em_2bX91Yk8h..."

welcome.tsx

200 · 1.2s

import { BirdClient } from "@messagebird/sdk";
import { render } from "@react-email/render";
import { WelcomeEmail } from "./emails/welcome";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

const { data, error } = await bird.email.send({
  from:    "Bird <hello@bird.com>",
  to:      ["ada@example.com"],
  subject: "Your invite is ready",
  html:    await render(<WelcomeEmail name="Ada" />),
}).safe();

if (error) throw error;
console.log(data.id);
// → "em_2bX91Yk8h..."

The single biggest lever on your reputation.

Suppression is built into the Bird Email API, not a list you maintain by hand. Mailbox providers punish senders who keep hitting dead addresses and spam-trap complaints; Bird stops those sends for you, automatically, the moment a recipient goes bad.

Five ways suppression protects you.

Automatic, reversible, and queryable.

01
Automatic on bounce + complaint.
Hard bounces, spam complaints, and unsubscribes suppress the recipient automatically. No code required.
02
Reversible.
Nothing is permanent. Remove an address if it recovers, and resume mailing it.
03
Manual entries.
Add addresses yourself: a known-bad list you're importing from another provider, say.
04
Queryable via API.
List, check, add, and remove suppressions programmatically, so your own systems stay in sync.
05
One list, every send.
Suppression applies across transactional and marketing mail, so a campaign can't re-mail an address a receipt just bounced.

Automatic by default, yours to control.

You never have to touch the list for it to work; bounces and complaints suppress on their own. But when you need to, the whole list is an API: add an address you already know is bad, look one up, or reinstate a recipient that recovered.

suppressions.ts

200

// Suppress an address you already know is bad.
await bird.email.suppressions.create({ email: "ada@example.com" });

// Look up why an address is on the list.
const { data } = await bird.email.suppressions.list({
  email: "ada@example.com",
});
// → [{ reason: "hard_bounce", applies_to: "all", created_at }]

// Reinstate one that recovered.
await bird.email.suppressions.remove("ada@example.com");

Four reasons, two scopes.

Not every suppression blocks every send. A recipient who unsubscribed from marketing still gets their password reset: complaints and unsubscribes scope to marketing, while hard bounces and manual adds block everything.

Reason	Triggered by	Blocks
hard_bounce	a permanent bounce	all mail (transactional + marketing)
complaint	a spam complaint	marketing only
unsubscribe	a list or one-click unsubscribe	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.

Suppressions FAQ

What gets suppressed automatically?+

Hard bounces, spam complaints, and unsubscribes. Once a recipient triggers one of these, Bird adds them to your suppression list and skips them on future sends.

Can I remove an address from the suppression list?+

Yes, suppression is reversible. If an address recovers, remove it from the list through the dashboard or API and resume mailing it.

Can I add my own suppressions?+

Yes. Add addresses manually, for instance a known-bad list you're importing, and they'll be skipped just like automatic entries.

Does suppression apply to both transactional and marketing email?+

Hard bounces and manual entries block every send. Complaints and unsubscribes scope to marketing only, so a transactional message like a password reset still reaches someone who opted out of your campaigns.

How do I test suppression without burning a real address?+

Send to the sandbox address suppressed@messagebird.dev. It short-circuits exactly as if the recipient were on your list (rejected with recipient_suppressed), without writing anything to the list, so it's reusable.

The rest of the Email platform

One API, one set of keys. Explore the other capabilities.

SendingTransactional and marketing email, templates, and batch sends.DeliverabilityAuthentication, IP warmup, suppression, and blocklist monitoring.AnalyticsPer-domain, per-ISP, per-IP delivery and engagement metrics.Dedicated IPsManaged dedicated IPs and pools, warmed automatically.Sending domainsDomain verification, DKIM/SPF/DMARC signing, and DMARC monitoring.BroadcastsMarketing campaigns: draft, target an audience, schedule, and send.AudiencesYour contacts and the audiences you target from a broadcast.Email API overviewThe full Email API: sending, deliverability, IPs, suppression, analytics, and broadcasts.

About 40% of the world's commercial email already runs on Bird.

Transactional and marketing email on infrastructure we've run for a decade. Suppression is one capability of the Bird Email API: sending, deliverability, dedicated IPs, and analytics ship with it.

Explore the Email platform Get started