Von einem anderen Anbieter migrieren
Nutzen Sie diese Anleitung, um Ihren Produktions-E-Mail-Versand von einem anderen Anbieter umzuziehen. Mappen Sie den Send-Request, veröffentlichen Sie DNS-Records, importieren Sie Unterdrückungen, übersetzen Sie Webhook-Events und testen Sie die Integration, bevor Sie Produktions-Traffic an Bird leiten.
Die Migrations-Checkliste:
- Send-Call mappen auf
POST /v1/email/messages - Sending-Domains und DNS umstellen
- Unterdrückungsliste importieren
- Webhooks auf unser Event-Vokabular umstellen
- Gegen die Mail-Sandbox verifizieren vor dem Cutover
Schritte 1, 3 und 4 hängen davon ab, welchen Anbieter Sie verlassen. Ihr Anbieter-Guide enthält das Feld-für-Feld-Payload-Mapping, wo Sie Ihre Unterdrückungsliste exportieren, und die Webhook-Event-Name-Übersetzungstabelle.
1. Send-Call mappen
Wir haben einen einzigen Single-Send-Endpoint, POST /v1/email/messages. Sie bauen ein flaches JSON-Payload (kein personalizations-Wrapper, kein MIME-Assembly) mit from, to/cc/bcc-Arrays, subject, html und/oder text, einer optionalen reply_to-Liste und headers für eigene E-Mail-Header. Ein erfolgreicher Send gibt 202 Accepted mit einer em_-präfixierten Message-ID zurück. Zustellergebnisse kommen asynchron über Webhooks und die Read-Endpoints. Das vollständige Payload mit allen Feldlimits und Defaults steht unter E-Mails senden. Das Feld-für-Feld-Mapping von Ihrem aktuellen Payload steht in Ihrem Anbieter-Guide. Falls Ihre Anwendung heute über SMTP einliefert, müssen Sie den Call möglicherweise gar nicht portieren: Wir akzeptieren SMTP-Einlieferung in dieselbe Pipeline, sodass dieser Schritt zu einem Credentials-Tausch wird.
Verwenden Sie tags für Filterdimensionen in Nachrichtenlisten, Analytics und Dashboard-Rollups. Verwenden Sie metadata für strukturierten Kontext, den Bird an der Nachricht speichert und bei API-Reads zurückgibt. Webhook-Events können diesen Kontext ebenfalls enthalten, Abmelde-Events können jedoch Nullwerte zurückgeben. Die Limits finden Sie unter Tags vs. Metadata.
Bevor Sie Code portieren, beachten Sie diese Unterschiede:
- Scheduling, gespeicherte Templates und Attachments lassen sich alle portieren. Verwenden Sie
scheduled_atfür zeitgesteuertes Senden. Verwenden Sietemplatestatt Inline-Content für gespeicherte Templates. Mappen Sie Dateien auf das Attachments-Array. - Unterdrückte Empfänger werden sichtbar abgelehnt. Eine unterdrückte Adresse erhält weiterhin eine
recipient_idund erscheint in der Empfängerliste der Nachricht mit Statusrejectedund einememail.rejected-Event (rejection_reason: recipient_suppressed), nie als stiller Drop. Selbst wenn alle Empfänger unterdrückt sind, wird der Request trotzdem mit202akzeptiert. Jeder Empfänger kommt als abgelehnt zurück. Siehe Unterdrückungen. - Setzen Sie
category: "transactional"für operationale E-Mails. Ein Send verwendet standardmäßigmarketing, und die Kategorie steuert die Unterdrückungs-Policy:marketingblockiert bei Beschwerden und Abmeldungen,transactionalstellt trotzdem zu. Newsletter und Kampagnen werden durch den Default korrekt behandelt. Markieren Sie Quittungen, Passwort-Resets und ähnliche operationale E-Mails alstransactional, damit sie nicht durch eine Abmeldung blockiert werden.
2. Domains und DNS umstellen
Registrieren Sie jede Sending-Domain mit POST /v1/email/domains oder unter Email > Domains und veröffentlichen Sie dann die Records aus dns_records. DKIM, der Return-Path-CNAME und eine DMARC-Policy sind Voraussetzung für den Versand. Ein bestehender DMARC-Record, auch auf einer übergeordneten Domain, zählt. Der Tracking-CNAME ist nur für gebrandetes Open- und Click-Tracking erforderlich. Sending-Domains behandelt die Records, den Verifizierungs-Lebenszyklus und das regionale Modell. Verwenden Sie den DNS-Record-Splitter, falls Ihr Provider einen aufgeteilten DKIM-Wert verlangt, und den DMARC-Policy-Generator, falls Sie eine Policy benötigen.
Ein Record, mit dem die meisten Anbieter Sie starten lassen, fehlt hier bewusst: Sie veröffentlichen keinen SPF-Record an Ihrem Domain-Apex. SPF wird gegen die Envelope-From-Domain ausgewertet, auf die der Return-Path-CNAME zu uns zeigt. Dadurch besteht SPF und ist aligned, ohne Ihren Apex zu berühren. Falls Ihr alter Anbieter Sie aufgefordert hat, einen include: zu Ihrem Apex-SPF-Record hinzuzufügen, lassen Sie ihn während der Übergangsphase stehen und entfernen Sie ihn nach dem Cutover. Er schadet und nützt E-Mails, die über uns gesendet werden, gleichermaßen nicht. Das Entfernen gibt einen der 10 DNS-Lookups frei, die Apex-SPF erlaubt. Die vollständige Erklärung steht unter DKIM, SPF & DMARC.
Sie können unsere Records veröffentlichen, während die Records Ihres alten Anbieters noch aktiv sind. Der DKIM-Record verwendet einen Selector von uns. Die Return-Path- und Tracking-CNAMEs sind neue Hostnamen, die Sie wählen, und Ihr bestehender DMARC-Record erfüllt die Anforderung unverändert. Beide Anbieter authentifizieren parallel, bis Sie bereit sind, den Traffic umzuschalten. Der Domain-Status ist regional, also registrieren Sie die Domain in jeder Region, aus der Sie senden.
3. Unterdrückungen importieren
Übernehmen Sie Ihre Unterdrückungsliste bevor Sie Produktions-Traffic über uns senden. Andernfalls gehen Ihre ersten Sends an Adressen, die beim alten Anbieter bereits gebounced oder sich beschwert haben, und das beschädigt die Reputation, die Sie schützen wollen.
Exportieren Sie die Liste von Ihrem aktuellen Anbieter (Ihr Anbieter-Guide enthält die genauen Endpoints) und fügen Sie dann jede Adresse hier mit POST /v1/email/suppressions hinzu:
while read -r address; do
curl -s -X POST https://us1.platform.bird.com/v1/email/suppressions \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"email\": \"$address\"}"
done < suppressions.txtZwei Dinge zu diesem Import-Pfad:
- Sie importieren eine Adresse pro Request. Die Unterdrückungen-API arbeitet mit Einzeleinträgen (CRUD), bei einer großen Liste iterieren Sie also über die exportierten Adressen. Der Call ist idempotent (
201für einen neuen Eintrag,200mit dem bestehenden Eintrag, falls die Adresse bereits manuell unterdrückt ist). Einen abgebrochenen Import können Sie daher gefahrlos erneut ausführen. - Importierte Adressen erhalten
reason: manual,applies_to: all, was jede Kategorie blockiert, einschließlich transaktionaler E-Mails. Das ist strenger als ein nativer Beschwerde-Eintrag, der nur nicht-transaktionale Sends blockiert. Falls Sie für bestimmte Adressen das kategoriebewusste Verhalten benötigen, siehe die Reason-Taxonomie unter Suppressions.
Künftig erzeugen Hard Bounces unabhängig von der Brand-Zuordnung Unterdrückungen auf Workspace-Ebene und lösen email_suppression.created aus. Auch Beschwerden ohne verlässliche Brand-Zuordnung erzeugen Unterdrückungen auf Workspace-Ebene und lösen email_suppression.created aus. Beschwerden mit Brand-Zuordnung werden als geschützte Präferenzen gespeichert. Abmeldungen werden als Präferenzen gespeichert. Abonnieren Sie auch die Präferenz-Events, selbst bei einem Workspace mit nur einer Brand, damit Ihr System diese Abmeldungen und spätere Einwilligungen spiegelt. Die Events email.complained, email.unsubscribed und email.list_unsubscribed auf Nachrichtenebene bleiben verfügbar. Den Unterschied erklärt E-Mail-Events.
4. Webhooks umstellen
Registrieren Sie einen Endpoint mit POST /v1/webhooks und abonnieren Sie ihn für eine explizite Liste von Event-Typen. Unsere Event-Namen folgen resource.action: email.accepted → email.processed → email.delivered auf dem Happy Path, mit email.deferred, email.bounced, email.complained, email.rejected, email.opened, email.clicked und dem Unsubscribe-Paar für den Rest. Die Event-Name-Übersetzung vom Vokabular Ihres aktuellen Anbieters steht in Ihrem Anbieter-Guide. Per-Event-Payload-Schemas stehen in der Events-Referenz.
Korrelieren Sie ausgehende Nachrichten-Events anhand von email_id und workspace_id; Events zum Lebenszyklus eines Empfängers enthalten zusätzlich recipient_id. Speichern Sie diese Zuordnung von Nachricht zu Kunde beim Senden. Behandeln Sie tags und metadata als zusätzlichen Kontext, wenn sie vorhanden sind: email.unsubscribed und email.list_unsubscribed aus Bird-Abmeldelinks liefern bei Einzelsendungen Nullwerte, auch wenn der Send sie enthielt. Abmelde-Events von Broadcasts können ebenfalls Nullwerte liefern, wenn dieser Kontext nicht verfügbar ist.
Nutzen Sie preference.revoked, preference.granted und preference.deleted als Signale, um Ihre Präferenz-Spiegelung zu aktualisieren. Diese Events identifizieren preference_id und transition_id mit Kanal, Handle, Brand, Absender und Themen-Geltungsbereich; sie enthalten keine Message-IDs und keine Send-Metadaten. Ihr timestamp ist der Zeitpunkt, ab dem die Aussage gilt, keine Version des Eintrags. Eine verspätete Beschwerde kann eine spätere Sammel-Einwilligung widerrufen, und verschiedene Änderungen können denselben Zeitstempel haben. Bestimmen Sie den aktuellen Status oder Geltungsbereich daher nicht, indem Sie Events sortieren oder transition_id als Reihenfolge behandeln.
Initialisieren und pflegen Sie eine vollständige Präferenz-Spiegelung in dieser Reihenfolge:
- Abonnieren Sie die Präferenz-Events und speichern Sie eingehende Benachrichtigungen dauerhaft, bevor Sie mit dem initialen Lesen beginnen.
- Befüllen Sie die Spiegelung aus allen Seiten der Präferenzliste des Workspace, ohne Filter für Kanal, Handle oder Brand. So finden Sie bestehende Abmeldungen, die nie eine Benachrichtigung an Ihren Endpoint ausgelöst haben. Speichern Sie für jeden Eintrag ID, Kanal, Handle, Brand, Absender und Themen-Geltungsbereich.
- Verarbeiten Sie gespeicherte und neue Benachrichtigungen, indem Sie die aktuelle Präferenz abrufen und für den betroffenen Kanal und Handle alle Seiten der Liste lesen. Vergleichen Sie die Geltungsbereiche, um Löschung und Neuanlage unter einer anderen ID zu erkennen. Gleichen Sie zusätzlich regelmäßig die vollständige, ungefilterte Liste des Workspace ab, einschließlich Empfängern, die in keiner Benachrichtigung und nicht in Ihrer lokalen Spiegelung vorkommen.
Lesezugriffe können einer Änderung hinterherhinken: Versuchen Sie es bei vorübergehenden Fehlern sowie bei unerwartet fehlendem oder älterem Zustand erneut. Ein fehlgeschlagener oder unvollständiger Lesezugriff darf keine lokale Sperre aufheben. Entfernen Sie einen gelöschten Eintrag erst, nachdem Sie sein Fehlen bestätigt haben; unabhängige Präferenzen und Unterdrückungen bleiben erhalten. Diese Spiegelung gleicht sich mit der Zeit an und ersetzt nicht die Prüfungen, die Bird beim Senden durchführt.
email_suppression.created identifiziert Hinzufügungen anhand von suppression_id, workspace_id und email. Für das Löschen einer Unterdrückung durch Kunden gibt es kein Event. Um Entfernungen im Dashboard oder über API zu erkennen, lesen Sie regelmäßig alle Seiten der Unterdrückungsliste des Workspace und gleichen Sie anhand der Unterdrückungs-ID ab. Entfernen Sie nach einem fehlgeschlagenen oder unvollständigen Scan keine Einträge; bestätigen Sie fehlende Einträge bei einem späteren Lesevorgang, bevor Sie sie entfernen. Halten Sie Unterdrückungseinträge getrennt von Präferenzen, damit das Entfernen einer Sperre keine andere aufhebt.
Wir signieren Zustellungen gemäß der Standard Webhooks-Spezifikation mit drei Headern: webhook-id, webhook-timestamp und webhook-signature, mit einem HMAC-SHA256 über {id}.{timestamp}.{raw body}. Falls Sie bereits Standard-Webhooks-Zustellungen einer anderen Plattform verifizieren, funktioniert derselbe Verifizierungscode auch hier. Andernfalls finden Sie die Verifizierungsanleitung, den Zeitplan, nach dem wir Zustellungen erneut versuchen, und das Replay-Tooling unter Webhooks & Events. Zustellungen erfolgen mindestens einmal und ungeordnet. Deduplizieren Sie deshalb anhand von webhook-id. Nutzen Sie die Zeitstempel der Nachrichten-Events, um den Ablauf einer Nachricht anzuzeigen; für Präferenzen und Unterdrückungen gleichen Sie wie oben beschrieben den aktuellen Zustand ab.
5. Vor dem Cutover in der Sandbox verifizieren
Bevor Sie Produktions-Traffic umleiten, testen Sie den portierten Send-Call und Ihren Handler für Nachrichten-Events gegen die Mail-Sandbox. Sandbox-Sends gehen an Magic-Adressen bei messagebird.dev und durchlaufen die echte Produktions-Pipeline: gleiche 202, gleiche Event-Sequenz, gleiche signierte Webhook-Zustellungen. Dabei erreichen sie nie ein Postfach und beeinflussen Ihre Reputation nicht.
Sandbox-Signale erzeugen keine Unterdrückungs- oder Beschwerde-Präferenz-Einträge. Testen Sie Ihre Spiegelung separat mit repräsentativen email_suppression.created-, preference.revoked-, preference.granted- und preference.deleted-Payloads aus den Webhook-Event-Verträgen, auch mit zwei Brands, die denselben Empfänger teilen. Berücksichtigen Sie diese Fälle:
- Eine unveränderte Abmeldung besteht bereits vor der Webhook-Registrierung. Die initiale ungefilterte Bestandsaufnahme findet sie ohne Benachrichtigung; die regelmäßige Bestandsaufnahme findet außerdem Einträge, die in Ihrer lokalen Spiegelung fehlen.
- Eine Abmeldung bei einer Einzelsendung hat leere Werte für
tagsundmetadata; Ihre gespeicherte Nachrichtenzuordnung identifiziert den Kunden trotzdem. - Eine Beschwerde trifft nach einer neueren Sammel-Einwilligung ein, oder eine ältere Abmeldung für alle Kategorien erweitert den Beschwerdeschutz, ohne ihren Gültigkeitszeitstempel vorzurücken. Stellen Sie die Events in umgekehrter Reihenfolge zu und prüfen Sie, dass der Abgleich den aktuellen widerrufenen Status und Geltungsbereich beibehält.
- Eine Präferenz wird gelöscht und neu angelegt, oder eine manuelle Unterdrückung wird im Dashboard entfernt. Der Abgleich entfernt nur Einträge, deren Fehlen bestätigt ist, und behält unabhängige Sperren bei.
- Eine Aktualisierung schlägt fehl oder liefert vorübergehend einen älteren Zustand. Ihr Handler versucht es erneut, und der regelmäßige Abgleich repariert die Spiegelung, ohne beim fehlgeschlagenen Lesezugriff Sperren aufzuheben.
Ein minimaler Pre-Cutover-Smoke-Test:
- Senden Sie an
delivered@messagebird.devund stellen Sie sicher, dass Ihr Handleremail.accepted→email.processed→email.deliveredverarbeitet. - Senden Sie an
bounce@messagebird.devund stellen Sie sicher, dass Ihre Bounce-Behandlung beiemail.bouncedauslöst (simulierte Bounces schreiben nicht in Ihre Unterdrückungsliste, sodass die Adresse wiederverwendbar bleibt). - Senden Sie an
suppressed@messagebird.devund stellen Sie sicher, dass Sieemail.acceptedgefolgt vonemail.rejectedverarbeiten, ohneemail.processedoder Delivery-Events danach. Das ist die Form, die jeder unterdrückte Empfänger in Produktion erzeugt; dasrejection_reason: recipient_suppressed-Detail steht am Empfänger-Record und den Events API. - Senden Sie eine
category: "marketing"-Nachricht und bestätigen Sie, dass die Kategorie dort erscheint, wo Sie sie beim Message-Read erwarten.
Verwenden Sie +label-Subaddressing (bounce+cutover-test@messagebird.dev), um Testfälle zu korrelieren. Die vollständige Adresse erscheint in Ihren Events. Sobald der Smoke-Test bestanden ist, schalten Sie den Traffic um. Richten Sie Ihre Anwendung auf uns aus und lassen Sie die DNS-Einträge des alten Anbieters bestehen, bis Ihre Domains hier capabilities.sending verifiziert zeigen. Beobachten Sie die ersten Stunden der echten Zustellungen im Dashboard und Ihrem Webhook-Stream.
Von einem bestimmten Anbieter migrieren
- SparkPost: Transmissions und SMTP, Template-Konvertierung, Unterdrückungen nach Geltungsbereich und Webhook-Events
- SendGrid:
personalizations→ flaches Payload,categories/custom_args→tags/metadata, diedropped↔email.rejected-Äquivalenz - Mailgun:
o:*/v:*/h:*-Parameter → eigenständige Felder, Export von Bounces, Beschwerden und Abmeldungen - Amazon SES: SendEmail v2 → ein Endpoint, Configuration Sets → Per-Message-Tracking-Flags, SNS → signierte Webhooks
- Resend: nahezu identische Payload-Struktur, Svix-signierte Webhooks → Standard Webhooks
- Postmark: kommagetrennte Empfänger → Arrays, Export der Unterdrückungen pro Stream, unsignierte Webhooks → signiert
- Brevo: Adress-Objekte → einfache Adressen, zwei separate Blocklists zu exportieren,
params→template.parameters - MailerSend: fünf Unterdrückungslisten, von denen die temporäre zurückbleibt,
personalization→ Per-Send-Parameter - Mailjet: das
Messages-Array → ein flaches Payload,EventPayload→metadata, Blocklist-Export - Mandrill: der
message-Wrapper und Body-Auth → flaches Payload und Bearer-Auth, Rejection-Blacklist-Export
Nächste Schritte
- E-Mails senden: das vollständige Send-Payload, Tags vs. Metadata, das asynchrone 202-Modell
- Sending-Domains: Registrierung, Verifizierungs-Lebenszyklus, Multi-Region-Setup
- DKIM, SPF & DMARC: was jeder Record nachweist und warum Apex-SPF nicht erforderlich ist
- Unterdrückungen: Gründe, Kategorien und die Management-API
- Webhooks & Events: Endpoint-Setup, Standard-Webhooks-Verifizierung, Retries und Replay
- Events: Per-Event-Payload-Schemas
- Testing-Sandbox: die vollständige Magic-Address-Liste und Walkthroughs
- API-Referenz: Request- und Response-Schemas für den Send-Endpoint
Verwandte Ressourcen
Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema.