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 Suppressions, ü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
Suppression-Liste 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 Suppression-Liste 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, bei API-Reads zurückgibt und in Webhook-Events mitliefert. Siehe Tags vs. Metadata für Limits.

Bevor Sie Code portieren, beachten Sie diese Unterschiede:

Scheduling, gespeicherte Templates und Attachments lassen sich alle portieren. Verwenden Sie scheduled_at für zeitgesteuertes Senden. Verwenden Sie template statt 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_id und erscheint in der Empfängerliste der Nachricht mit Status rejected und einem email.rejected-Event (rejection_reason: recipient_suppressed), nie als stiller Drop. Selbst wenn alle Empfänger unterdrückt sind, wird der Request trotzdem mit 202 akzeptiert. Jeder Empfänger kommt als abgelehnt zurück. Siehe Suppressions.
Setzen Sie category: "transactional" für operationale E-Mails. Ein Send verwendet standardmäßig marketing, und die Kategorie steuert die Suppression-Policy: marketing blockiert bei Beschwerden und Abmeldungen, transactional stellt trotzdem zu. Newsletter und Kampagnen werden durch den Default korrekt behandelt. Markieren Sie Quittungen, Passwort-Resets und ähnliche operationale E-Mails als transactional, 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. Suppressions importieren

Übernehmen Sie Ihre Suppression-Liste 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:

Codebeispiel

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

Zwei Dinge zu diesem Import-Pfad:

Sie importieren eine Adresse pro Request. Die Suppressions-API ist Single-Entry-CRUD, eine große Liste bedeutet also, über die exportierten Adressen zu iterieren. Der Call ist idempotent (201 für einen neuen Eintrag, 200 mit dem bestehenden Eintrag, falls die Adresse bereits manuell unterdrückt ist), sodass ein erneuter Lauf eines teilweisen Imports sicher ist.
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 verwalten Sie Bounces nicht mehr selbst: Wir unterdrücken Hard Bounces und Beschwerden automatisch und feuern email_suppression.created, damit Ihre Systeme die Suppression-Liste spiegeln können. Abmeldungen werden stattdessen als angegebene Präferenz gespeichert und über email.unsubscribed und email.list_unsubscribed gespiegelt, nicht über das Suppression-Event.

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.

Die Korrelation lässt sich sauber portieren. Jedes Event enthält die Identifikatoren email_id, recipient_id und workspace_id. Es liefert außerdem tags und metadata aus dem Send-Request mit. Das gibt Ihnen den Kontext zurück, den Ihr alter Anbieter per Payload-Echo bereitgestellt hat, ohne einen zusätzlichen Lookup. Setzen Sie Ihre internen IDs in metadata beim Send und lesen Sie sie direkt aus jedem Event.

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 von einer anderen Plattform verifizieren, funktioniert exakt derselbe Verifizierungscode hier. Andernfalls finden Sie das Verifizierungsrezept, den Retry-Zeitplan und das Replay-Tooling unter Webhooks & Events. Zustellungen sind at-least-once und ungeordnet, also deduplizieren Sie anhand von webhook-id und sortieren Sie nach dem Payload-timestamp, dieselbe Disziplin, die Ihr aktueller Handler bereits haben sollte.

5. Vor dem Cutover in der Sandbox verifizieren

Bevor Sie Produktions-Traffic umleiten, führen Sie Ihre vollständige Integration (den portierten Send-Call, Ihren Webhook-Handler, Ihre Suppression-Spiegelung) gegen die Mail-Sandbox aus. Sandbox-Sends gehen an Magic-Adressen bei messagebird.dev und durchlaufen die echte Produktions-Pipeline: gleiche 202, gleiche Event-Sequenz, gleiche signierte Webhook-Zustellungen, ohne jemals eine Inbox zu erreichen oder Ihre Reputation zu beeinflussen.

Ein minimaler Pre-Cutover-Smoke-Test:

Senden Sie an delivered@messagebird.dev und stellen Sie sicher, dass Ihr Handler email.accepted → email.processed → email.delivered verarbeitet.
Senden Sie an bounce@messagebird.dev und stellen Sie sicher, dass Ihre Bounce-Behandlung bei email.bounced auslöst (simulierte Bounces schreiben nicht in Ihre Suppression-Liste, sodass die Adresse wiederverwendbar bleibt).
Senden Sie an suppressed@messagebird.dev und stellen Sie sicher, dass Sie email.accepted gefolgt von email.rejected verarbeiten, ohne email.processed oder Delivery-Events danach. Das ist die Form, die jeder unterdrückte Empfänger in Produktion erzeugt; das rejection_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, 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

SendGrid: personalizations → flaches Payload, categories/custom_args → tags/metadata, die dropped ↔ email.rejected-Äquivalenz
Mailgun: o:*/v:*/h:*-Parameter → erstklassige Felder, Bounces/Complaints/Unsubscribes-Export
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, Per-Stream-Suppression-Dumps, unsignierte Webhooks → signiert
Brevo: Adress-Objekte → einfache Adressen, zwei separate Blocklists zu exportieren, params → template.parameters
MailerSend: fünf Suppression-Listen, 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
Suppressions: Reasons, 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