Unterdrückungen
Ihr Workspace besitzt eine Unterdrückungsliste: eine Menge von E-Mail-Adressen, an die wir nicht zustellen. Hard Bounces und Spam-Beschwerden werden automatisch eingetragen, und Sie können Adressen auch selbst hinzufügen. Wiederholtes Versenden an Adressen, die bouncen oder Spam melden, kann dazu führen, dass Mailbox-Provider Ihre Domain blockieren. Deshalb stoppen wir diese Sendungen, bevor sie die Plattform verlassen.
Eine neue Abmeldung erzeugt keinen Suppression-Eintrag. Sie speichert die vom Empfänger selbst geäußerte Präferenz und keine Zustellbarkeitsinformation, deshalb erscheint sie auf dem Tab Preferences statt hier. Siehe Abmeldelinks für Details.
Verwalten Sie die Liste unter Email > Suppressions, über die Suppressions-API oder mit bird email suppressions.
Die drei Gründe und was sie blockieren
Jeder Eintrag hat einen reason, der angibt, warum die Adresse gelistet ist, und eine applies_to-Richtlinie, die steuert, welche Kategorien blockiert werden:
| Grund | applies_to | Marketing-Kategorie | Transaktionale Kategorie |
|---|---|---|---|
| hard_bounce | all | Blockiert | Blockiert |
| complaint | non_transactional | Blockiert | Erlaubt |
| manual | all | Blockiert | Blockiert |
Die Aufteilung ergibt sich aus der Bedeutung jedes Grundes:
- hard_bounce: Die Adresse existiert nicht. Das Senden ist in jeder Kategorie sinnlos, daher wird alles blockiert.
- complaint: eine Aussage über unerwünschte E-Mails. Jemand, der Ihren Newsletter als Spam gemeldet hat, benötigt möglicherweise trotzdem ein Passwort-Reset oder eine Bestellbestätigung. Daher werden nur nicht-transaktionale Sendungen blockiert.
- manual: eine bewusste Entscheidung von Ihnen oder Ihrem Team. Wir hinterfragen sie nicht, daher blockiert eine manuelle Unterdrückung jede Kategorie, einschließlich transaktionaler.
Eine Adresse kann pro Grund einen Eintrag haben. Ein Hard Bounce und eine frühere Beschwerde stehen als separate Einträge nebeneinander, und die Zustellung bleibt blockiert, solange ein blockierender Eintrag vorhanden ist. Wir behandeln Unbekanntes restriktiv: Wenn ein Eintrag mit einem applies_to zurückkommt, das Ihre Integration noch nie gesehen hat, behandeln Sie es als Blockierung jeder Kategorie – so handhaben wir es selbst auch.
Note: reason: unsubscribe is deprecated on the suppressions API. New unsubscribes record a preference instead of a suppression. The deprecated ?reason=unsubscribe filter still returns legacy suppression records with origin: unsubscribe_link or origin: unsubscribe_event until those records are removed.
Wie Adressen automatisch hinzugefügt werden
Wir fügen Unterdrückungen als Reaktion auf Empfängersignale hinzu, sodass ein Bounce oder eine Beschwerde kein Handeln Ihrerseits erfordert:
| Auslöser | Resultierende Unterdrückung |
|---|---|
| Hard Bounce (email.bounced) | reason: hard_bounce, origin: bounce_event, applies_to: all |
| Out-of-Band-Hard-Bounce (email.out_of_band_bounce) | reason: hard_bounce, origin: bounce_event, applies_to: all |
| Spam-Beschwerde (email.complained) | reason: complaint, origin: complaint_event, applies_to: non_transactional |
Eine Abmeldung, ob über den Link im Nachrichtentext oder die Ein-Klick-Schaltfläche, erscheint hier nicht: Sie erfasst eine Präferenz auf dem Tab Preferences, statt eine Zeile zu dieser Liste hinzuzufügen.
Nur ein Bounce der Klasse hard führt zur Unterdrückung, und die Klassifizierungstabelle zeigt, welche bounce_class-Werte als hard gelten. Zwei Ergebnisse, die wie Fehler aussehen, lassen die Adresse versendbar:
- Soft Bounces und Zustellverzögerungen (email.deferred oder email.bounced mit bounce_type: "soft"): vorübergehende Fehler wie ein volles Postfach. Wir versuchen es erneut.
- Sendeseitige Ablehnungen: Generierungsfehler und Richtlinienablehnungen sind Probleme mit der Sendung, nicht mit der Adresse. Sie erzeugen email.rejected-Events und keine Unterdrückung.
Wiederholte Signale für eine Adresse, die bereits aus demselben Grund unterdrückt ist, lassen den ursprünglichen Eintrag unverändert, einschließlich seines created_at. Der Eintrag behält source_email_id und source_recipient_id, die eine automatische Unterdrückung mit der genauen Nachricht und dem Empfänger verknüpfen, die sie ausgelöst haben. Diese beiden Felder beantworten die Support-Frage "why did this person stop getting our email" und sind bei manuellen Ergänzungen null.
Jede Ergänzung, ob automatisch oder manuell, löst ein email_suppression.created-Event an Ihren Webhook-Endpunkt aus, mit dem suppression_id, der unterdrückten email, dem reason und dem workspace_id, sodass Ihr eigenes System die Liste ohne Polling spiegeln kann:
Codebeispiel
{
"type": "email_suppression.created",
"timestamp": "2026-07-23T14:52:03.192524705Z",
"data": {
"email": "user@example.com",
"reason": "manual",
"suppression_id": "sup_01ky7qckqrf06r38g49b9kxdbc",
"workspace_id": "ws_01ky7m21hjffh9s8kq76gyb1xf"
}
}Unterdrückungen über die API verwalten
Die API fügt einzelne Einträge hinzu, listet sie auf, sucht sie und löscht sie. Adressen werden vor der Speicherung und Suche in Kleinbuchstaben umgewandelt und erscheinen nie in einem URL-Pfad, weil ein Pfad in Zugriffsprotokollen landet und eine E-Mail-Adresse personenbezogene Daten sind. Um den Eintrag für eine Adresse zu finden, filtern Sie die Liste mit ?email=.
Jedes SDK stellt diese Operationen als typisierte Methoden auf seiner suppressions-Ressource bereit.
Adresse hinzufügen
const suppression = await bird.suppressions.add({ email: "user@example.com" });
console.log(suppression.id);suppression = client.suppressions.add(email="user@example.com")
print(suppression.id)suppression, err := client.Suppressions.Add(context.Background(), bird.SuppressionsAddParams{
Email: "user@example.com",
})
if err != nil {
log.Fatal(err)
}
fmt.Println(suppression.Id)$suppression = $bird->suppressions->add(
(new SuppressionCreate())->setEmail('user@example.com'),
);
echo $suppression->getId();bird email suppressions add --email user@example.comcurl -X POST https://us1.platform.bird.com/v1/email/suppressions \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "email": "user@example.com" }'Manuelle Ergänzungen erhalten reason: manual und applies_to: all, sodass sie jede Kategorie blockieren. Der Aufruf ist idempotent: Eine neue Unterdrückung gibt 201 Created zurück, und eine bereits manuell unterdrückte Adresse gibt 200 OK mit dem bestehenden Eintrag zurück statt eines Konflikts. In beiden Fällen ist der Body das Unterdrückungsobjekt:
Codebeispiel
{
"applies_to": "all",
"created_at": "2026-07-23T14:52:03.192524705Z",
"email": "user@example.com",
"id": "sup_01ky7qckqrf06r38g49b9kxdbc",
"origin": "api_key",
"reason": "manual",
"scope": {
"id": "ws_01ky7m21hjffh9s8kq76gyb1xf",
"type": "workspace"
}
}Das Feld origin zeichnet auf, wie der Eintrag entstanden ist. Manuelle Ergänzungen erhalten api_key oder user, je nachdem, ob sich der Aufrufer mit einem API-Schlüssel oder einer Dashboard-Sitzung authentifiziert hat. Automatische Ergänzungen erhalten bounce_event oder complaint_event, je nachdem, welches Signal sie ausgelöst hat.
Auflisten und nachschlagen
Diese Aufrufe geben die erste Seite zurück. In Go startet das leere dritte Argument die Paginierung; übergeben Sie den NextCursor der vorherigen Seite, um die nächste Seite abzurufen.
const page = await bird.suppressions.list({ limit: 25 });
console.log(page.data.length);page = client.suppressions.list(limit=25)
print(len(page.data))page, err := client.Suppressions.ListPage(context.Background(), bird.SuppressionsListParams{Limit: 25}, "")
if err != nil {
log.Fatal(err)
}
fmt.Println(len(page.Data))$page = $bird->suppressions->list(['limit' => 25])->fetch();
echo count($page->data);bird email suppressions list --limit 25curl "https://us1.platform.bird.com/v1/email/suppressions?limit=25" \
-H "Authorization: Bearer $BIRD_API_KEY"Die Liste ist cursor-paginiert, neueste zuerst, und nach reason filterbar. Um eine einzelne Adresse zu prüfen, übergeben Sie sie als Query-Parameter email:
const page = await bird.suppressions.list({ email: "user@example.com" });
console.log(page.data.length);page = client.suppressions.list(email="user@example.com")
print(len(page.data))page, err := client.Suppressions.ListPage(context.Background(), bird.SuppressionsListParams{
Email: "user@example.com",
}, "")
if err != nil {
log.Fatal(err)
}
fmt.Println(len(page.Data))$page = $bird->suppressions->list(['email' => 'user@example.com'])->fetch();
echo count($page->data);bird email suppressions list --email user@example.comcurl "https://us1.platform.bird.com/v1/email/suppressions?email=user@example.com" \
-H "Authorization: Bearer $BIRD_API_KEY"Der Filter email vergleicht Groß-/Kleinschreibung-unabhängig per Präfix: user@example.com trifft auch auf user@example.com.au. Vergleichen Sie jede zurückgegebene Adresse mit der vollständigen angefragten Adresse und folgen Sie next_cursor durch alle Seiten, bevor Sie entscheiden, ob ein passender Eintrag existiert. Für eine Adresse können mehrere Einträge vorliegen. MCP-Aufrufer können email_suppressions_check für diese Exakt-Adress-Suche verwenden.
Sobald Sie eine Suppression-ID haben, gibt GET /v1/email/suppressions/{suppression_id} diesen einen Eintrag zurück: suppressions.get in den SDKs oder bird email suppressions get <id> auf der CLI.
Adresse entfernen
await bird.suppressions.remove("sup_01ky7qckqrf06r38g49b9kxdbc");client.suppressions.remove("sup_01ky7qckqrf06r38g49b9kxdbc")if err := client.Suppressions.Remove(context.Background(), "sup_01ky7qckqrf06r38g49b9kxdbc"); err != nil {
log.Fatal(err)
}$bird->suppressions->remove('sup_01ky7qckqrf06r38g49b9kxdbc');bird email suppressions remove sup_01ky7qckqrf06r38g49b9kxdbc --yescurl -X DELETE https://us1.platform.bird.com/v1/email/suppressions/sup_01ky7qckqrf06r38g49b9kxdbc \
-H "Authorization: Bearer $BIRD_API_KEY"Ein Grund kann auf diesem Weg nicht entfernt werden. Ein complaint-Eintrag wird nur für einen angemeldeten Dashboard-Benutzer gelöscht; ein API-Schlüssel erhält 422 SuppressionNotRemovableByAPIKey. hard_bounce- und manual-Einträge lassen sich auf beiden Wegen entfernen.
Gibt 204 No Content zurück und entfernt den Eintrag dauerhaft. Andere Einträge für dieselbe Adresse bleiben bestehen, und die Zustellung bleibt blockiert, solange ein verbleibender Eintrag die Nachrichtenkategorie sperrt. Um Einträge nach Adresse zu entfernen, paginieren Sie die ?email=-Suche, wählen Sie nur Treffer mit vollständiger Adresse aus und löschen Sie jeden gewünschten Eintrag per ID. Überlegen Sie gut, bevor Sie einen hard_bounce-Eintrag entfernen, denn eine Adresse, die nach wie vor nicht existiert, bounced beim nächsten Versand und unterdrückt sich erneut selbst.
Was passiert, wenn Sie an eine unterdrückte Adresse senden
Wir lehnen den Empfänger dort ab, wo Sie es sehen können. Der Empfänger erhält einen recipient_id und erscheint in der Empfängerliste der Nachricht mit dem Status rejected. Die Events API und Ihre Webhooks zeichnen ein email.rejected-Event mit rejection_reason: "recipient_suppressed" auf. Die übrigen Empfänger werden normal zugestellt.
Die Nachricht selbst wird weiterhin mit einem 202 akzeptiert, auch wenn alle ihre Empfänger unterdrückt sind. Wir lösen Suppressions erst nach Annahme des Versands auf, während wir die Nachricht verarbeiten. Eine Adresse, die Sie jetzt hinzufügen, greift daher innerhalb weniger Minuten und stoppt keinen bereits laufenden Versand.
Testen mit der Sandbox
Die Test-Sandbox testet Suppression-Verhalten deterministisch. Ein Versand an suppressed@messagebird.dev verhält sich so, als stünde die Adresse auf Ihrer Liste: Der Empfänger wird mit rejection_reason: "recipient_suppressed" abgelehnt und erreicht nie die Zustellung. Die Sandbox-Bounce- und Complaint-Adressen (bounce@messagebird.dev, complaint@messagebird.dev) durchlaufen die echte Event-Pipeline, schreiben aber nichts in Ihre Suppression-Liste, sodass dieselben Testadressen über mehrere Durchläufe hinweg wiederverwendbar bleiben.
Nächste Schritte
- Kategorien: transactional versus marketing, und wie die Kategorie mit der Suppression-Richtlinie zusammenwirkt
- Abmeldelinks: wie Opt-outs eine geäußerte Präferenz statt einer Suppression speichern
- Events und Webhooks: die email.rejected-Payload und die Lifecycle-Events, die automatische Suppressions auslösen
- Test-Sandbox: Magic-Adressen zur Simulation aller Zustellergebnisse
- API-Referenz: Suppressions: vollständige Request- und Response-Schemas
- Was passiert, wenn sich jemand abmeldet: ein Video, das einen Empfänger von der Abmeldeseite bis zu einem abgelehnten Versand begleitet
Verwandte Ressourcen
Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema. Die Ressourcen sind auf Englisch.
Das Konzept verstehenWhat is one-click unsubscribe, and how do I implement List-Unsubscribe?Die Funktion erkundenEmail opt-outsDem Lernpfad folgenOperate messaging reliably
Implementierungs-Briefing erhalten