Migration von Mailgun
Diese Seite ordnet Mailguns POST /v3/{domain}/messages-Parameter, Suppressionslisten und Webhook-Events Bird zu. Folgen Sie der Hauptmigrationsanleitung der Reihe nach und verwenden Sie diese Zuordnungen für die Schritte 1, 3 und 4.
Ü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 Mailgun 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/mailgun.md for the parameter, 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 Mailgun usage in this repository before you change anything: the /v3/{domain}/messages call sites and any SDK wrappers around them, every o:, v: and h: prefixed parameter I pass, my webhook handler and the URL it is registered at, and every Mailgun domain I send from. Mailgun scopes almost everything per domain, so keep that list of domains: the next two steps both work through it.
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 Mailgun 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 suppressions from Mailgun and import them into Bird before any production traffic goes through Bird, so my first sends do not reach addresses that already bounced or complained. Mailgun keeps three lists per domain, so pull GET /v3/{domain}/bounces, GET /v3/{domain}/complaints and GET /v3/{domain}/unsubscribes for every domain you found. 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 webhook handler using the mapping tables on the provider page. Two things need attention rather than translation: Mailgun reports one failed event with a severity field where Bird has separate deferred and bounced events, and Bird signs deliveries per Standard Webhooks rather than Mailgun's scheme, so treat verification as a rewrite. See 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 Mailgun path is a separate step that comes later: ask me again and wait for me to reply with the words retire the Mailgun 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.Den Send-Aufruf zuordnen
Mailguns formularcodierte Parameterpräfixe (o:-Optionen, v:-Variablen, h:-Header) werden alle zu erstklassigen JSON-Feldern auf POST /v1/email/messages:
| Funktion | Mailgun | Bird |
|---|---|---|
| Absender | from | from |
| Empfänger | to / cc / bcc | to / cc / bcc (Arrays) |
| Betreff | subject | subject |
| Inhalt | html / text | html / text (mindestens eins) |
| Reply-to | h:Reply-To | reply_to (Array) |
| Eigene Header | h:X-* | headers (String-→-String-Objekt) |
| Filterbare Labels | o:tag | tags: {name, value}-Paare |
| Roundtrip-Kontext | v:* / X-Mailgun-Variables | metadata: beliebiges JSON |
| Gespeichertes Template | template + t:variables | template + template.parameters |
| Zeitplanung | o:deliverytime | scheduled_at |
| Open-/Click-Tracking | o:tracking-opens / o:tracking-clicks | 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.
Portierungshinweise:
- Der Request wird zu JSON. Mailgun akzeptiert Multipart-Formulardaten. Wir erwarten einen JSON-Body mit Content-Type: application/json. Das ist in der Regel die größte mechanische Änderung bei der Portierung.
- v:-Variablen wurden in Events zurückgegeben. Unser metadata funktioniert genauso. Wir geben Ihre metadata (und tags) bei jedem Webhook-Event zusammen mit email_id/recipient_id zurück, sodass Ihre Handler sie ohne zusätzlichen Lookup erhalten.
- Empfängervariablen lassen sich nicht eins zu eins portieren. Mailguns recipient-variables personalisieren viele Empfänger in einem Aufruf. Bei uns übernimmt diese Aufgabe der Batch-Endpoint, ein Eintrag pro Empfänger, jeweils mit eigenem Inhalt oder eigenen parameters-Werten für die {{ token }}-Substitution.
- Gespeicherte Templates lassen sich direkt portieren. Mailguns template-Parameter wird unserem template-Feld mit Werten in template.parameters zugeordnet. Siehe Senden mit einem Template.
- Anhänge lassen sich direkt portieren. Mailgun-Multipart-Dateien attachment / inline werden zu unserem attachments-Array mit Base64-content (setzen Sie content_id für Inline-Bilder). Siehe Anhänge.
Suppressionen exportieren
Mailgun führt drei Listen pro Domain. Exportieren Sie jede und verarbeiten Sie sie mit der Import-Schleife:
- GET /v3/{domain}/bounces
- GET /v3/{domain}/complaints
- GET /v3/{domain}/unsubscribes
Wiederholen Sie das pro Sendedomain. Mailguns Listen sind domainbezogen, unsere Suppressionen dagegen Workspace-bezogen. Importiert wird also die Vereinigung der Listen aller Ihrer Domains.
Webhook-Events übersetzen
Mailgun signalisiert temporäre und permanente Fehler mit einem failed-Event plus einem severity-Feld. Wir trennen sie:
| Ergebnis | Mailgun | Bird |
|---|---|---|
| Akzeptiert/verarbeitet | accepted | email.accepted → email.processed |
| Zugestellt | delivered | email.delivered |
| Temporärer Fehler | failed (temporary) | email.deferred |
| Permanenter Bounce | failed (permanent) | email.bounced / email.out_of_band_bounce |
| Spam-Beschwerde | complained | email.complained |
| Blockiert/unterdrückt | (keine) | email.rejected |
| Öffnung | opened | email.opened |
| Klick | clicked | email.clicked |
| Abmeldung | unsubscribed | email.list_unsubscribed |
email.rejected hat kein Mailgun-Gegenstück: Wir melden unterdrückte Empfänger sichtbar (Status rejected, rejection_reason: recipient_suppressed), statt sie stillschweigend zu überspringen. Fügen Sie dafür einen Handler hinzu, anstatt es als Bounce zu behandeln.
Auch die Verifizierung ändert sich: Mailgun signiert mit einem HMAC über timestamp + token innerhalb des signature-Objekts der Payload, während wir gemäß der Standard-Webhooks-Spezifikation mit Headern statt Payload-Feldern signieren. Ersetzen Sie Ihren Verifizierungscode durch das Rezept in Webhooks & Events.
Umstellung
Arbeiten Sie Domains & DNS und den Sandbox-Smoke-Test in der Hauptanleitung durch. Beide sind anbieterunabhängig.
Nächste Schritte
- Sendedomains: 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
- Suppressionen: Überprüfen Sie Ihre importierte Liste und wie wir sie ab jetzt 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