Sign inGet started

Migration von SendGrid

Diese Seite ordnet SendGrids v3-Mail-Send-Payload, Suppressionslisten und Event Webhook Bird zu. Folgen Sie der Hauptanleitung zur Migration der Reihe nach und verwenden Sie diese Zuordnungen für die Schritte 1, 3 und 4.

Übergeben Sie das an Ihren Agenten

Fügen Sie diesen Text in Claude Code, Cursor oder Codex ein. Der Agent arbeitet diese Seite gegen Ihr eigenes Repository ab und nutzt dazu 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 SendGrid 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/sendgrid.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 SendGrid usage in this repository before you change anything: the /v3/mail/send call sites and any SDK wrappers around them, the Event Webhook 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 suppressions from SendGrid 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. SendGrid splits these across GET /v3/suppression/bounces, GET /v3/suppression/spam_reports, GET /v3/suppression/unsubscribes, and GET /v3/asm/groups/{group_id}/suppressions for each unsubscribe group worth carrying over. 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. Bird signs deliveries per Standard Webhooks rather than SendGrid'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 SendGrid path is a separate step that comes later: ask me again and wait for me to reply with the words retire the SendGrid 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

SendGrids POST /v3/mail/send verpackt Empfänger in einem personalizations-Array. Unser POST /v1/email/messages ist eine flache Payload, daher wird jede Personalisierung zu einem eigenen Versand (oder einem Batch-Eintrag).
FunktionSendGridBird
Absenderfrom.emailfrom
Empfängerpersonalizations[].to / cc / bccto / cc / bcc (Arrays)
Betreffsubjectsubject
Inhaltcontent[] (type + value)html / text (mindestens eines)
Reply-toreply_to / reply_to_listreply_to (Array)
Eigene Headerheadersheaders (string → string Objekt)
Filterbare Labelscategoriestags: {name, value}-Paare
Round-Trip-Kontextcustom_argsmetadata: beliebiges JSON
Gespeichertes Templatetemplate_id + dynamic_template_datatemplate + template.parameters
Zeitplanungsend_atscheduled_at
Öffnungs-/Klick-Trackingtracking_settingstrack_opens / track_clicks (Standard true)
IP-Poolip_pool_nameip_pool_id (ipp_... oder ipp_shared)
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:
  • categories sind einfache Strings. Unsere Tags sind Paare. Eine Kategorie wie "welcome" wird zu {"name": "category", "value": "welcome"}. Wählen Sie einen stabilen name, damit Ihre Dashboards genauso filtern wie Ihre SendGrid-Statistiken.
  • custom_args wurden in jedem Event 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 den Kontext ohne zusätzlichen Lookup erhalten.
  • Dynamische Templates werden zu gespeicherten Templates. template_id plus dynamic_template_data werden zu template (referenziert per ID oder Slug) plus template.parameters im selben Send-Aufruf. Siehe Versand mit einem Template. send_at wird direkt auf scheduled_at abgebildet.
  • Anhänge werden direkt portiert. SendGrids attachments (base64 content, type, filename, content_id für Inline) werden Feld für Feld auf unser attachments-Array abgebildet.
  • Abmeldegruppen (asm) lassen sich nicht als Konzept portieren: Wir behandeln List-Unsubscribe auf Kategorie-Ebene, sodass marketing-Mail automatisch suppressionsbewusste Abmeldebehandlung erhält.

Suppressionen exportieren

SendGrid verteilt Suppressionen auf mehrere Endpunkte. Exportieren Sie jeden und führen Sie ihn durch die Import-Schleife:
  • GET /v3/suppression/bounces
  • GET /v3/suppression/spam_reports
  • GET /v3/suppression/unsubscribes (globale Abmeldungen)
  • GET /v3/asm/groups/{group_id}/suppressions für jede Abmeldegruppe, die Sie übernehmen möchten

Webhook-Events übersetzen

ErgebnisSendGrid Event WebhookBird
Akzeptiert/verarbeitetprocessedemail.acceptedemail.processed
Zugestelltdeliveredemail.delivered
Temporärer Fehlerdeferredemail.deferred
Permanenter Bouncebounceemail.bounced / email.out_of_band_bounce
Spam-Beschwerdespamreportemail.complained
Blockiert/unterdrücktdroppedemail.rejected
Öffnungopenemail.opened
Klickclickemail.clicked
Abmeldungunsubscribe / group_unsubscribeemail.unsubscribed / email.list_unsubscribed
Die Äquivalenz droppedemail.rejected ist der entscheidende Testpunkt: Wie SendGrid melden wir unterdrückte Empfänger sichtbar (Status rejected, rejection_reason: recipient_suppressed), statt sie stillschweigend zu verwerfen, sodass Ihre Audit-Logik sauber portiert werden kann.
Die Verifizierung ändert mehr als nur die Event-Namen: SendGrids Event Webhook signiert mit einem ECDSA-Public-Key, während wir nach dem Standard Webhooks HMAC-Schema signieren. Ersetzen Sie Ihren Verifizierungscode durch das Rezept in Webhooks & Events. SendGrid bündelt Events außerdem in JSON-Arrays. Wir liefern ein Event pro Request.

Umstellung

Arbeiten Sie Domains & DNS und den Sandbox-Rauchtest in der Hauptanleitung durch. Beide sind anbieterunabhängig.

Nächste Schritte

  • Sending Domains: Registrierung, Verifizierungslebenszyklus und die DNS-Einträge, die Sie umleiten
  • Webhooks & Events: Endpoint-Einrichtung und Standard-Webhooks-Verifizierung
  • Testing Sandbox: Rauchtest der neuen Integration vor der Umstellung
  • Suppressionen: Überprüfen Sie Ihre importierte Liste und wie wir sie ab jetzt pflegen