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; Those sends are stopped 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 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
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. 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

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.

The rest of the Email platform

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

SendingTransactional and marketing email, templates, and batch sends.TemplatesStored, versioned email templates, personalized per recipient at send.DeliverabilityAuthentication, IP warmup, suppression, and per-provider visibility.AnalyticsDelivery and engagement metrics per mailbox provider, domain, and IP.Dedicated IPsManaged dedicated IPs and pools, warmed automatically.Sending domainsDNS records generated for you, DKIM signing, and continuous re-verification.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