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 Abmeldung steht nicht auf dieser Liste. Sie erfasst die vom Empfänger selbst geäußerte Präferenz statt eines Zustellbarkeitsfaktums und befindet sich daher auf dem Tab Preferences. Unter Abmeldelinks erfahren Sie, wie das funktioniert.

Verwalten Sie die Liste unter Email > Suppressions, über die Suppressions-API oder mit bird email suppressions.

Die Suppressions-Seite im Dashboard mit unterdrückten Adressen, ihrem Grund, Ursprung und Erstellungsdatum sowie einer Schaltfläche zum Erstellen einer Unterdrückung

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. Unsubscribes now record a preference instead of a suppression, so ?reason=unsubscribe matches nothing.

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=.

Die SDK-Beispiele greifen auf Unterdrückungen über die Raw-Request-Methode jedes Clients zu, die dieselbe Authentifizierung, Wiederholungsversuche und Base-URL-Behandlung wie ein typisierter Aufruf bietet. Die Antwortstruktur ist die, die Sie deklarieren.

Adresse hinzufügen

type Suppression = { id: string; email: string; reason: string };

const suppression = await bird.request<Suppression>({
  method: "POST",
  path: "/v1/email/suppressions",
  body: { email: "user@example.com" },
});

client.post("/v1/email/suppressions", body={"email": "user@example.com"})

var suppression struct {
	Id     string `json:"id"`
	Email  string `json:"email"`
	Reason string `json:"reason"`
}
if err := client.Post(context.Background(), "/v1/email/suppressions", map[string]any{
	"email": "user@example.com",
}, &suppression); err != nil {
	log.Fatal(err)
}

$suppression = $bird->post('/v1/email/suppressions', body: [
    'email' => 'user@example.com',
]);

curl -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" }'

In der CLI deckt bird email suppressions sowohl list als auch remove ab; das Hinzufügen einer Adresse erfolgt über die API.

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

type Suppressions = { data: Array<{ id: string; email: string; reason: string }> };

const suppressions = await bird.request<Suppressions>({
  method: "GET",
  path: "/v1/email/suppressions?limit=25",
});
console.log(suppressions.data.length);

suppressions = client.get("/v1/email/suppressions?limit=25")
print(len(suppressions["data"]))

var out struct {
	Data []struct {
		Email  string `json:"email"`
		Reason string `json:"reason"`
	} `json:"data"`
}
if err := client.Get(context.Background(), "/v1/email/suppressions?limit=25", &out); err != nil {
	log.Fatal(err)
}
fmt.Println(len(out.Data))

$suppressions = $bird->get('/v1/email/suppressions', query: ['limit' => 25]);

bird email suppressions list --limit 25

curl "https://us1.platform.bird.com/v1/email/suppressions?limit=25" \
  -H "Authorization: Bearer $BIRD_API_KEY"

Die Liste ist cursorbasiert paginiert, neueste zuerst, und nach reason filterbar. Um eine einzelne Adresse zu prüfen, übergeben Sie sie als email-Query-Parameter:

const suppressions = await bird.request({
  method: "GET",
  path: "/v1/email/suppressions?email=user@example.com",
});
console.log(suppressions.data.length);

suppressions = client.get("/v1/email/suppressions?email=user@example.com")
print(len(suppressions["data"]))

var out struct {
	Data []struct {
		Email  string `json:"email"`
		Reason string `json:"reason"`
	} `json:"data"`
}
if err := client.Get(context.Background(), "/v1/email/suppressions?email=user@example.com", &out); err != nil {
	log.Fatal(err)
}
fmt.Println(len(out.Data))

$suppressions = $bird->get('/v1/email/suppressions', query: ['email' => 'user@example.com']);

bird email suppressions list --email user@example.com

curl "https://us1.platform.bird.com/v1/email/suppressions?email=user@example.com" \
  -H "Authorization: Bearer $BIRD_API_KEY"

Ein leeres data-Array bedeutet, dass die Adresse nicht unterdrückt ist, und mehrere Einträge werden zurückgegeben, wenn mehr als ein Grund zutrifft. Der email-Filter gleicht Groß-/Kleinschreibung ignorierend per Präfix ab: Eine vollständige Adresse liefert die Einträge dieser Adresse, und ein Fragment wie alice liefert jede unterdrückte Adresse, die damit beginnt.

Adresse entfernen

await bird.request({
  method: "DELETE",
  path: "/v1/email/suppressions/sup_01ky7qckqrf06r38g49b9kxdbc",
});

client.delete("/v1/email/suppressions/sup_01ky7qckqrf06r38g49b9kxdbc")

if err := client.Delete(context.Background(), "/v1/email/suppressions/sup_01ky7qckqrf06r38g49b9kxdbc", nil); err != nil {
	log.Fatal(err)
}

$bird->delete('/v1/email/suppressions/sup_01ky7qckqrf06r38g49b9kxdbc');

bird email suppressions remove sup_01ky7qckqrf06r38g49b9kxdbc --yes

curl -X DELETE https://us1.platform.bird.com/v1/email/suppressions/sup_01ky7qckqrf06r38g49b9kxdbc \
  -H "Authorization: Bearer $BIRD_API_KEY"

Gibt 204 No Content zurück. Das Löschen ist endgültig: Wir behalten nichts, und die Adresse wird wieder versendbar. Das Löschen nach Adresse erfordert zwei Aufrufe: eine ?email=-Suche nach der ID und dann das Löschen. Eine Adresse, die aus mehreren Gründen unterdrückt ist, erfordert das Löschen jedes blockierenden Eintrags. Seien Sie vorsichtig beim Entfernen eines hard_bounce-Eintrags, denn eine Adresse, die weiterhin nicht existiert, bounct beim nächsten Versand und unterdrückt sich selbst erneut.

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 die Unterdrückung nach dem Annehmen der Sendung auf, während wir die Nachricht verarbeiten. Eine Adresse, die Sie jetzt hinzufügen, greift daher innerhalb weniger Minuten und stoppt nie eine Sendung, die bereits unterwegs ist.

Testen mit der Sandbox

Die Test-Sandbox prüft die Unterdrückungsbehandlung deterministisch. Das Senden 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 -Beschwerde-Adressen (bounce@messagebird.dev, complaint@messagebird.dev) durchlaufen die reale Event-Pipeline, schreiben aber nichts in Ihre Unterdrückungsliste, sodass dieselben Testadressen über alle Durchläufe hinweg wiederverwendbar bleiben.

Nächste Schritte

Kategorien: transactional versus marketing, und wie die Kategorie mit der Unterdrückungsrichtlinie zusammenwirkt
Abmeldelinks: wie Opt-outs eine geäußerte Präferenz statt einer Unterdrückung erfassen
Events und Webhooks: der email.rejected-Payload und die Lifecycle-Events, die automatische Unterdrückungen auslösen
Test-Sandbox: spezielle Adressen zur Simulation jedes Zustellergebnisses
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 einer abgelehnten Sendung begleitet

Verwandte Ressourcen