Migration von Mailjet
Diese Seite ordnet Mailjets Send-API-v3.1-Payload, Blocklist und Event API den Entsprechungen in Bird zu. Folgen Sie dem Hauptleitfaden zur Migration der Reihe nach und nutzen Sie diese Zuordnungen für die Schritte 1, 3 und 4.
Die größte strukturelle Änderung betrifft den Envelope. Mailjet verpackt jeden Versand in ein Messages-Array aus PascalCase-Objekten (POST /v3.1/send). Wir erwarten ein flaches, kleingeschriebenes JSON-Objekt pro POST /v1/email/messages, und mehrere unabhängige Nachrichten gehen an den Batch-Endpoint statt in das Messages-Array.
Übergeben Sie dies Ihrem Agenten
Fügen Sie dies in Claude Code, Cursor oder Codex ein. Der Agent arbeitet diese Seite gegen Ihr eigenes Repository ab und nutzt die Bird-Oberfläche, die er bereits hat: den MCP-Server, falls einer verbunden ist, oder die CLI, falls sie installiert und angemeldet ist.
Codebeispiel
I am moving an email integration from Mailjet to Bird. Route through it with me.
1. Check what you already have before setting anything up. If Bird's MCP server is connected, use its tools. If the Bird CLI is installed and signed in, use that. Either one is enough, and every step below is an action you take with whichever you have. Only if neither is present, follow https://bird.com/docs/ai/set-up-your-agent.md to set one up and sign me in. Every Bird docs page serves Markdown at its own URL with `.md` appended, so fetch that rather than the HTML.
2. Read https://bird.com/docs/guides/email/migrate/mailjet.md for the payload, suppression and event mapping, and https://bird.com/docs/guides/email/migrate.md for the order the steps go in.
3. Find and list my Mailjet usage in this repository before you change anything: the POST /v3.1/send call sites and any SDK wrappers around them, the event handler and the URL it is registered at, and every domain I send from.
4. Register each of those sending domains with Bird and give me the DNS records to publish, following https://bird.com/docs/guides/email/sending-domains.md. Leave every DNS record my current provider uses exactly as it is: Bird's records are published alongside them and both providers authenticate side by side until I switch traffic. Publishing DNS affects mail for the whole domain, so show me the records and let me publish them.
5. Export my blocklist from Mailjet and import it into Bird before any production traffic goes through Bird, so my first sends do not reach addresses that already bounced or complained. Read it through the contact-management API, or from the contact statistics pages if that is what I have access to. The Bird import takes one address per request and is idempotent, so a partial re-run is safe. https://bird.com/docs/guides/email/suppressions.md has the reason taxonomy.
6. Port the send call and the event handler using the mapping tables on the provider page. Mailjet posts a Messages array of PascalCase objects, and each entry becomes either one flat Bird send or one entry in a batch, so tell me which shape my call sites map onto before you rewrite them. EventPayload becomes metadata. Bird signs deliveries per Standard Webhooks rather than Mailjet's scheme, so treat verification as a rewrite rather than a URL change: https://bird.com/docs/guides/webhooks.md and https://bird.com/docs/guides/email/events.md.
7. Run my whole integration against Bird's mail sandbox before any production traffic, following https://bird.com/docs/guides/email/testing-sandbox.md. Sandbox sends run the real pipeline without reaching an inbox or touching my sending reputation.
8. Stop and ask me wherever a step needs a decision. Do not point production traffic at Bird until I have seen the sandbox results and replied with the words cut over to Bird. Retiring the Mailjet path is a separate step that comes later: ask me again and wait for me to reply with the words retire the Mailjet path. A reply that agrees without naming what it is authorising is not authorisation. Finish by telling me what is left that only a person can do.Send-Aufruf zuordnen
| Funktion | Mailjet (Send API v3.1) | Bird |
|---|---|---|
| Absender | From: { "Email", "Name" } | from: String oder { "email", "name" } |
| Empfänger | To / Cc / Bcc: [{ "Email", "Name" }] | to / cc / bcc: Arrays |
| Betreff | Subject | subject |
| Inhalt | TextPart / HTMLPart | text / html (mindestens eins) |
| Reply-to | ReplyTo: { "Email", "Name" } | reply_to: Array |
| Eigene Header | Headers | headers: String-→-String-Objekt |
| Roundtrip-Kontext | EventPayload (String), wird bei Events zurückgegeben | metadata: beliebiges JSON |
| Eigene Send-ID | CustomID, wird bei Events zurückgegeben | metadata oder tags |
| Gespeichertes Template | TemplateID + Variables | template + template.parameters |
| Anhänge | Attachments: { "ContentType", "Filename", "Base64Content" } | attachments: { "content_type", "filename", "content" } |
| Inline-Bilder | InlinedAttachments, mit ContentID | attachments mit content_id |
| Tracking | Account-/Template-Einstellung | track_opens / track_clicks (Standard true) |
| Kategorie | (keine) | category: marketing (Standard) oder transactional |
Unsere Feldlimits und Standardwerte (Empfängeranzahl, Tag- und Metadaten-Limits) finden Sie unter E-Mail senden.
Hinweise zur Portierung:
- Entpacken Sie das Messages-Array. Ein einzelner Mailjet-Versand ist ein Eintrag in Messages. Bei uns ist das der gesamte Request-Body. Ein Messages-Array mit mehreren Einträgen wird auf unseren Batch-Endpoint abgebildet. Wiederholte Felder in einem Request können den Batch nicht abbilden.
- Groß-/Kleinschreibung wechselt von PascalCase zu Kleinbuchstaben. Jedes Feld wird umbenannt: HTMLPart → html, TextPart → text, From.Email → from.email. Das ist mechanisch, betrifft aber jeden Versand.
- EventPayload wird zu metadata. Mailjet gibt einen einzelnen EventPayload-String bei jedem Event zurück. Wir geben strukturierte metadata (JSON) und tags bei jedem Webhook-Event zurück, sodass Sie Korrelationsdaten in typisierte Felder aufteilen können. Siehe Tags vs. Metadaten.
- CustomID ist ein Korrelations-Handle, und Retries erfordern eine eigene Lösung. Mailjets CustomID wird für das Tracking an die Events durchgereicht; es dedupliziert nicht. Mailjets Deduplizierung ist X-Mailjet-DeduplicateCampaign, ein Boolean in Verbindung mit X-Mailjet-Campaign, der verhindert, dass eine Kampagne denselben Empfänger zweimal erreicht – eine kampagnenbezogene Garantie, kein sicherer Retry eines einzelnen Requests. Legen Sie bei uns Ihre Korrelations-ID in metadata oder tags ab und verwenden Sie den Idempotency-Key-Header, um einen wiederholten Request sicher zu machen.
- Gespeicherte Templates lassen sich direkt portieren. Mailjets TemplateID + Variables werden auf unser template-Feld (referenziert per ID oder Slug) mit Werten in template.parameters abgebildet. Siehe Versand mit einem Template. Auch Templating-Logik über einfache Variablenersetzung hinaus lässt sich portieren: Mailjets TemplateLanguage-Bedingungen und -Schleifen werden zu Liquid-{% if %} und -{% for %} in unserem Template.
- Anhänge lassen sich direkt portieren. Mailjets Base64Content entspricht unserem Base64-content, und InlinedAttachments + ContentID werden zu attachments-Einträgen mit content_id. Siehe Anhänge.
Suppressions exportieren
Mailjet speichert nicht erreichbare und unerwünschte Adressen auf seiner Blocklist (Hard-/Soft-Bounces und blockierte Sendungen) und erfasst Spam- und Abmeldesignale separat. Exportieren Sie die blockierten und gebouncten Adressen aus Mailjets Kontaktstatistik-Seiten oder rufen Sie sie über die Kontaktverwaltungs-API ab und führen Sie die Liste durch die Import-Schleife. Falls Sie Marketing-Mails versenden, übernehmen Sie auch als abgemeldet markierte Kontakte, damit diese Präferenzen den Wechsel überstehen.
Webhook-Events übersetzen
Mailjets Event API sendet einen Trigger pro Event-Typ. Die Zuordnung zu unserem Event-Vokabular:
| Ergebnis | Mailjet | Bird |
|---|---|---|
| Akzeptiert/verarbeitet | (keins) | email.accepted → email.processed |
| Zugestellt | sent | email.delivered |
| Permanenter Bounce | bounce | email.bounced / email.out_of_band_bounce |
| Blockiert | blocked | email.rejected |
| Spam-Beschwerde | spam | email.complained |
| Öffnung | open | email.opened |
| Klick | click | email.clicked |
| Abmeldung | unsub | email.unsubscribed / email.list_unsubscribed |
Zwei Unterschiede, die Codeänderungen erfordern:
- Wir melden die Phasen vor der Zustellung explizit. Mailjets sent wird ausgelöst, sobald der Mailserver des Empfängers die Nachricht annimmt – das entspricht unserem email.delivered. Wir senden zusätzlich email.accepted und email.processed davor, sodass Sie den Fortschritt eines Versands vor der Zustellbestätigung sehen. Behandeln Sie diese früheren Events nicht als Zustellung.
- Events beziehen sich auf einzelne Empfänger. Mailjet ordnet Events über MessageID zu. Unsere Zustellevents enthalten recipient_id neben email_id, sodass ein Versand an mehrere Empfänger pro Empfänger einen eigenen Event-Stream erzeugt. Wir signieren Zustellungen gemäß der Standard-Webhooks-Spezifikation. Siehe Webhooks & Events zur Verifizierung.
Umstellung
Arbeiten Sie Domains & DNS und den Sandbox-Smoke-Test im Hauptleitfaden durch. Beides ist anbieterunabhängig.
Nächste Schritte
- Sende-Domains: Registrierung, Verifizierungslebenszyklus und die DNS-Einträge, die Sie umleiten
- Webhooks & Events: Endpoint-Einrichtung und Standard-Webhooks-Verifizierung
- Test-Sandbox: Smoke-Test der neuen Integration vor der Umstellung
- Suppressions: Überprüfung Ihrer importierten Liste und wie wir sie ab hier pflegen
Verwandte Ressourcen
Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema. Die Ressourcen sind auf Englisch.
Anleitung ansehenGetting started with emailDie Funktion erkundenEmailDem Lernpfad folgenBuild your first integrationImplementierungsleitfadenSend your first email
Übung ausprobieren und ein Implementierungs-Briefing erhalten