Sign inGet Started

E-Mail-Events

Wir senden Events, während jeder Empfänger den Zustellprozess durchläuft. Ein Versand an drei Adressen erzeugt drei unabhängige Streams, korreliert über email_id und recipient_id. Diese Seite definiert die E-Mail-Event-Typen. Siehe Webhooks für Signaturen, erneute Versuche, Reihenfolge und Replay.

Jeder Empfänger startet bei email.accepted, dann email.processed. Ein Broadcast-Empfänger ist eine eigene Nachricht und bekommt daher auch eine eigene email.accepted, allerdings nur in den Events API und im E-Mail-Log, nicht als Webhook. Von dort wird die Nachricht vom empfangenden Server akzeptiert (email.delivered), verzögert und erneut versucht (email.deferred, was sich zu zugestellt oder gebounced auflöst), vom empfangenden Server abgelehnt (email.bounced) oder erhält gar keinen Zustellversuch (email.rejected). Nach einer Zustellung kann der Stream mit email.out_of_band_bounce, email.complained, email.opened, email.clicked, email.unsubscribed und email.list_unsubscribed weitergehen.

Jeder Empfänger endet in genau einem terminalen Status: delivered, bounced, complained oder rejected, zurückgegeben als status pro Empfänger von GET /v1/email/messages/{message_id}/recipients. Engagement-Events ändern ihn nie: Ein Empfänger, der geöffnet hat, bleibt delivered. Ein verspäteter Bounce-Report ändert ihn jedoch, weil der empfangende Server eine bereits erteilte Annahme zurückzieht, sodass der Empfänger von delivered zu bounced wechselt. Die Nachricht als Ganzes hat ihren eigenen zusammengefassten Status und Zähler pro Zustand auf GET /v1/email/messages/{message_id}.

Der Event-Envelope

Events kommen als Drei-Felder-Envelope an, den jeder Webhook verwendet: type, timestamp (wann das Event eingetreten ist, RFC 3339) und ein typspezifisches data-Objekt.

Codebeispiel
{
  "type": "email.delivered",
  "timestamp": "2026-07-23T14:51:47.107Z",
  "data": {
    "email_id": "em_01ky7qc398fmxraqtxn604zeq9",
    "recipient_id": "er_01ky7qc398fmwsc96nt6anrbqs",
    "workspace_id": "ws_01ky7m21hjffh9s8kq76gyb1xf",
    "recipient": "delivered@messagebird.dev",
    "recipient_role": "to",
    "tags": [{ "name": "category", "value": "welcome" }],
    "metadata": { "order_id": "ord_123" },
    "broadcast_id": null,
    "brand_id": null
  }
}

Jedes ausgehende Event auf Empfängerebene enthält email_id, recipient_id, workspace_id, die recipient-Adresse und deren Envelope recipient_role (to, cc oder bcc). Speichern Sie beim Versand eine Zuordnung von Workspace und Nachrichten-ID zu Ihren eigenen Datensätzen. tags und metadata enthalten den Versandkontext, sofern verfügbar. Sie sind null, wenn kein Kontext angegeben wurde, sowie bei email.unsubscribed und email.list_unsubscribed aus Bird-Abmeldelinks für einzelne Versendungen. Abmelde-Events von Broadcasts können ebenfalls null zurückgeben, wenn ihr Kontext nicht verfügbar ist.

broadcast_id benennt den Broadcast, zu dem ein Versand gehört, und ist null bei einem Versand ohne Broadcast. Ein Abmeldelink aus E-Mails, die vor Einführung des Feldes gesendet wurden, benennt keinen Broadcast. Ein Opt-out über einen solchen Link meldet daher null, unabhängig davon, ob ein Broadcast die E-Mail gesendet hat. Behandeln Sie null bei email.unsubscribed und email.list_unsubscribed als nicht aussagekräftig. broadcast_id erreicht Sie nur über den Webhook: Die Events API unten geben jedes Event ohne dieses Feld zurück. Event-Typen fügen Felder hinzu, die in den folgenden Abschnitten beschrieben werden.

Webhooks für ausgehende E-Mails enthalten außerdem das optionale Feld brand_id. Die API für Nachrichten-Events enthält dieses Feld nicht.

Dieselben Events sind nachträglich über GET /v1/email/messages/{message_id}/events abfragbar, wo jedes außerdem eine id (ev_-Präfix) und eine occurred_at hat. Nutzen Sie sie zum Nachtragen fehlender Daten, Replay oder Abgleich mit dem, was Ihr Endpunkt empfangen hat. Einige Felder erreichen Sie nur über diese API und nicht über den Webhook; die jeweilige Event-Beschreibung kennzeichnet jedes einzelne.

Lebenszyklus-Events

email.accepted

Wir haben den Versand angenommen und mit der Zustellvorbereitung begonnen. Wird einmal pro angefordertem Empfänger ausgelöst und ist das erste Event in diesem Stream. Ein Broadcast-Empfänger bekommt ebenfalls eines, weil jeder Empfänger eine eigene Nachricht ist, aber es wird aufgezeichnet statt zugestellt: Lesen Sie es aus den Events API oder dem E-Mail-Log, nicht von Ihrem Webhook-Endpunkt. Payload: nur die Identity-Basis.

email.processed

Die Nachricht ist aufgebaut und zur Zustellung an den Mailserver des Empfängers eingereiht. Payload: nur die Identity-Basis über den Webhook; die Events API ergänzen mailbox_provider und mailbox_provider_region, die Klassifizierung des empfangenden Mailsystems (zum Beispiel gmail, NA), vorhanden wenn ermittelbar, sonst null. Der Vergleich des timestamp dieses Events mit dem von email.accepted ergibt unsere eigene Verarbeitungszeit bei einem einzelnen Versand. Ein Broadcast hat kein solches Intervall: Annahme und Verarbeitung tragen denselben Dispatch-Zeitpunkt, sodass die beiden Zeitstempel übereinstimmen statt eine Verarbeitung einzurahmen, und die Annahme erreicht Sie nur über die Events API, als occurred_at.

email.delivered

Der empfangende Mailserver hat die Nachricht akzeptiert und die Verantwortung dafür übernommen. Dieses Event bestätigt weder Inbox-Platzierung noch Lesen. Inbox Insights liefert stichprobenbasierte Platzierungsschätzungen; Öffnungs- und Klick-Events zeichnen Tracking-Anfragen auf. Payload: nur die Identity-Basis über den Webhook; die Events API ergänzen sending_ip, die Adresse, von der die Nachricht gesendet wurde, was relevant ist, wenn ein Zustellproblem auf eine IP zurückgeht, plus mailbox_provider und mailbox_provider_region.

email.deferred

Ein vorübergehender Fehler: Der empfangende Server hat uns gebeten, es später erneut zu versuchen (volles Postfach, Greylisting, Begrenzung der Anfragerate). Wir versuchen es automatisch erneut, und der Empfänger löst sich schließlich zu email.delivered oder email.bounced auf, sodass dieses Event informativ und nicht terminal ist, und ein Empfänger kann vorher mehrfach verzögert werden. Payload: bounce_type, bounce_class, defer_reason (der vom Server angegebene Grund) und sending_ip über den Webhook; die Events API ergänzen mailbox_provider und mailbox_provider_region.

Fehler-Events

email.bounced

Ein permanenter Fehler zum Zeitpunkt SMTP: Der empfangende Server hat die Nachricht abgelehnt, und der terminale Status des Empfängers wird bounced. Payload: bounce_type (siehe Klassifizierungstabelle), bounce_class, bounce_code (der SMTP-Antwortcode, zum Beispiel 550), bounce_description (der vom Server angegebene Grund) und sending_ip über den Webhook; die Events API ergänzen mailbox_provider und mailbox_provider_region. Ein Hard Bounce unterdrückt die Adresse.

email.out_of_band_bounce

Ein verspäteter Bounce: Der empfangende Server hat die Nachricht zum Zeitpunkt SMTP akzeptiert und danach einen Bounce-Report gesendet. Er hat dieselbe Klassifizierung wie email.bounced (bounce_type, bounce_class, bounce_code, bounce_description, sending_ip über den Webhook; mailbox_provider und mailbox_provider_region aus den Events API). Wenn der Report als Bounce klassifiziert wird (jede Klasse in der Tabelle), hat der Server seine frühere Annahme zurückgezogen, sodass der Empfänger von delivered zu bounced wechselt. Reports, deren Klasse nicht in der Tabelle steht, etwa Auto-Replies, werden auf der Timeline aufgezeichnet und lassen den Status unverändert. Ein harter Out-of-Band-Bounce unterdrückt die Adresse ebenfalls.

email.rejected

Die Nachricht für den Empfänger hat den entfernten Mailserver nie erreicht, daher wurde keine Zustellung versucht. Das unterscheidet eine Ablehnung von einem Bounce, bei dem der empfangende Server die Nachricht zurückweist. Payload: rejection_reason, auch im Empfängerdatensatz enthalten:

rejection_reasonBedeutung
recipient_suppressedDer Empfänger ist durch die Unterdrückungsliste oder eine erklärte Präferenz blockiert, daher wurde kein Zustellversuch unternommen
transmission_failedDie Nachricht konnte nicht zur Zustellung übermittelt werden
generation_failureDie Nachricht konnte nicht zur Zustellung aufgebaut werden, ein Template- oder Inhaltsproblem
policy_rejectionDie Versandrichtlinie hat die Nachricht abgelehnt
domain_unverifiedDie Absendedomain war nicht verifiziert
quota_exceededDas Versandkontingent der Organisation wurde erreicht
recipient_not_allowedDer Empfänger war für diesen Versand nicht zulässig; Versendungen über eine gemeinsame Onboarding-Domain erreichen nur verifizierte Mitglieder Ihres Workspace
workspace_suspendedDer Workspace ist gesperrt. Diese E-Mail wurde daher nicht gesendet und wird auch nach der Reaktivierung nicht gesendet

Bird ergänzt im Laufe der Zeit weitere Ablehnungsgründe. Ein Webhook oder Empfängerdatensatz kann daher einen Grund enthalten, der noch nicht in dieser Tabelle steht. Behandeln Sie unbekannte Gründe als Ablehnungen mit einer nicht aufgeführten Ursache. Bewahren Sie den Wert auf, um ihn später nachschlagen zu können.

Die Events API ergänzen außerdem mailbox_provider und mailbox_provider_region, wenn das empfangende Mailsystem vor der Ablehnung klassifiziert werden konnte.

email.complained

Der Empfänger hat die Nachricht als Spam markiert, und der Mailbox-Anbieter hat dies über seine Feedback-Schleife zurückgemeldet. Beschwerden kommen nach der Zustellung an und setzen den terminalen Status auf complained. Payload: feedback_type, die Art des vom Anbieter gesendeten Reports, zum Beispiel abuse oder fraud, und null, wenn der Anbieter keine Angabe machte, plus mailbox_provider und mailbox_provider_region aus den Events API. Eine Beschwerde blockiert Marketing-E-Mails für die zugeordnete Brand oder für den gesamten Workspace, wenn keine zuverlässige Brand-Zuordnung verfügbar ist. Halten Sie Ihre Beschwerderate niedrig: Anbieter drosseln Absender, die Reports ansammeln.

Engagement-Events

email.opened

Das Tracking-Pixel im Nachrichtentext wurde geladen. Payload: ip_address und user_agent, wenn bekannt; die Events API ergänzen is_prefetched, country (ISO 3166-1 alpha-2, abgeleitet von der Client-IP), mailbox_provider und mailbox_provider_region. Prüfen Sie is_prefetched, bevor Sie eine Öffnung zählen. Es ist true, wenn eine Inbox-Datenschutzfunktion das Pixel automatisch abgerufen hat, anstatt dass eine Person die Nachricht geöffnet hat, und das Mitzählen solcher Abrufe bläht Ihre Öffnungsrate auf. Öffnungs- und Klick-Tracking behandelt die Instrumentierung.

email.clicked

Der Empfänger hat einen getrackten Link angeklickt. Payload: url (der angeklickte Link), ip_address und user_agent, wenn bekannt; die Events API ergänzen country, mailbox_provider und mailbox_provider_region. Klicks sind in der Regel ein stärkeres Engagement-Signal als Öffnungen, weil Datenschutz-Proxys Tracking-Pixel automatisch laden können.

email.unsubscribed

Der Empfänger hat den Abmeldelink im Nachrichtentext verwendet. Payload: nur die Identity-Basis über den Webhook; die Events API ergänzen mailbox_provider und mailbox_provider_region. Zeichnet eine Opt-out-Präferenz auf, die Marketing-E-Mails blockiert. Abmeldelinks beschreibt, wie der Link in Ihre E-Mail gelangt.

email.list_unsubscribed

Der Empfänger hat den Ein-Klick-Abmeldebutton verwendet, den der Mailbox-Anbieter in seiner eigenen UI rendert, gesteuert über die List-Unsubscribe-Header der Nachricht. Payload: nur die Identity-Basis über den Webhook (plus mailbox_provider und mailbox_provider_region aus den Events API); der Mechanismus ist der Event-Typ selbst, weshalb er von email.unsubscribed getrennt ist. Zeichnet ebenfalls eine Opt-out-Präferenz auf, die Marketing-E-Mails blockiert.

Events auf Nachrichtenebene

Zwei Events beschreiben die gesamte Nachricht statt eines einzelnen Empfängers. Ihr data enthält deshalb email_id, workspace_id, brand_id, tags und metadata, aber keine Empfängeridentität. Beide gehören zum geplanten Versand.

email.scheduled

Wir haben einen Versand mit einem scheduled_at in der Zukunft angenommen. Payload: die Nachrichtenebene-Basis plus scheduled_at. Wenn dieser Zeitpunkt eintritt, startet der Lebenszyklus pro Empfänger bei email.accepted.

email.canceled

Eine geplante Nachricht wurde abgebrochen, bevor sie versendet wurde, sodass sie keinerlei Empfänger-Lebenszyklus-Events erzeugt. Payload: nur die Nachrichtenebene-Basis.

Inbound- und Mailbox-Events

email.received deckt eingehende E-Mails ab. Es wird ausgelöst, wenn wir eine eingehende Nachricht empfangen und parsen. Sein Payload umfasst die inbound_message_id, Adressierung, Betreff und Authentifizierungsergebnisse. Setup, Payload und der Abruf-API sind in E-Mail empfangen beschrieben. Eine Mailbox hat darüber hinaus ihre eigene email_mailbox.*-Familie, behandelt im Mailbox-Leitfaden.

Bounce-Klassifizierung

bounce_class ist die numerische Bounce-Klassifizierung, die bei email.bounced, email.out_of_band_bounce und email.deferred enthalten ist. Sie fasst sich in die grobe Klasse bounce_type zusammen und behält den feingranularen Code, sodass Sie ein volles Postfach von einem Routing-Fehler unterscheiden können, obwohl beide als soft gemeldet werden:

bounce_classbounce_typeBedeutung
1undeterminedDie Antwort des empfangenden Servers war mehrdeutig
10, 30hardPermanenter Fehler: ungültige Adresse oder eine Domain, die nicht existiert
20 bis 24, 40, 70, 100softVorübergehender Fehler: volles Postfach, Server vorübergehend nicht erreichbar, DNS- oder Routing-Problem
25adminAdministrative Ablehnung: Relaying verweigert, Domain auf Blocklist
50 bis 54blockDer empfangende Server hat die sendende IP abgelehnt

Jede Klasse außerhalb dieser Liste wird auf undetermined abgebildet. Nur hard-Bounces unterdrücken die Adresse; soft, block, admin und undetermined tun dies nicht, weil die Adresse möglicherweise noch zustellbar ist.

Automatische Unterdrückung

Hard Bounces erzeugen Unterdrückungen für den gesamten Workspace. Spam-Beschwerden mit zuverlässiger Brand-Zuordnung zeichnen geschützte E-Mail-Präferenzen für diese Brand auf; Beschwerden ohne zuverlässige Zuordnung erzeugen Unterdrückungen für den gesamten Workspace.

EventErgebnisWas blockiert wird
email.bounced oder email.out_of_band_bounce mit bounce_type: "hard"Unterdrückung mit reason: hard_bounceAlle Kategorien über alle Brands hinweg
email.complained mit zuverlässiger Brand-ZuordnungPräferenz mit origin: complaintNicht-transaktionale E-Mails dieser Brand
email.complained ohne zuverlässige Brand-ZuordnungUnterdrückung mit reason: complaintNicht-transaktionale E-Mails über alle Brands hinweg

email.complained bleibt das Beschwerde-Event auf Nachrichtenebene. Eine Brand-Beschwerde, die die wirksame Präferenz auf widerrufen ändert, löst zusätzlich preference.revoked aus, mit preference_id und brand_id. Wiederholte Beschwerden müssen keinen weiteren Präferenzwechsel erzeugen. Rufen Sie die Präferenz ab, um ihren aktuellen Ursprung, Status und die gespeicherte complaint_message_id zu erhalten.

Abonnieren Sie preference.revoked, preference.granted und preference.deleted, wenn Sie Empfängerentscheidungen synchronisieren, auch in einem Workspace mit nur einer Brand. Aktualisieren Sie damit die aktuelle Präferenz und ihren Geltungsbereich für Kanal, Handle, Brand, Absender und Thema. Die Zeitstempel einer Präferenz geben den Zeitpunkt der wirksamen Einwilligung an, nicht die Reihenfolge der Änderungen. Wenn Sie danach sortieren, können Sie den aktuellen Status oder Geltungsbereich nicht rekonstruieren. Bestätigen Sie Löschungen durch einen Abgleich und behalten Sie dabei unabhängige Präferenzen und Unterdrückungen des Workspace bei.

Eine Brand-bezogene Beschwerde löst kein email_suppression.created aus. Dieses Event beschreibt Einträge in die Unterdrückungsliste des Workspace, mit suppression_id, email, reason und workspace_id. Für das Entfernen von Unterdrückungen gibt es keinen Kunden-Webhook. Eine Kopie braucht daher zusätzlich einen regelmäßigen Abgleich der vollständigen, paginierten Liste. Bestehende Beschwerde-Unterdrückungen auf Workspace-Ebene behalten ihren Geltungsbereich. Folgen Sie dem Synchronisierungsrezept im Migrationsleitfaden. Versuchen Sie dabei Lesevorgänge erneut, die fehlschlagen oder eine Änderung noch nicht widerspiegeln.

email.unsubscribed und email.list_unsubscribed zeichnen ebenfalls Präferenzen auf. Abmeldelinks erklärt ihre Wirkung. Unterdrückungen erklärt, wie Sie den Beschwerdeschutz prüfen und ein neueres individuelles Opt-in erfassen.

Spätere Versendungen an eine unterdrückte Adresse werden sofort als email.rejected mit rejection_reason: "recipient_suppressed" abgelehnt und zählen nie gegen Ihre Zustellbarkeit.

Nächste Schritte