Migreren van SendGrid
Deze pagina vertaalt het v3 Mail Send-payload, de suppressielijsten en de Event Webhook van SendGrid naar Bird. Volg de hoofdmigratiegids op volgorde en gebruik deze vertalingen voor stap 1, 3 en 4.
Geef dit aan je agent
Plak dit in Claude Code, Cursor of Codex. De agent werkt deze pagina door tegen je eigen repository, via het Bird-oppervlak dat al beschikbaar is: de MCP-server als er een is verbonden, de CLI als die is geïnstalleerd en ingelogd.
Codevoorbeeld
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.Vertaal de verzendaanroep
SendGrids POST /v3/mail/send verpakt ontvangers in een personalizations-array. Ons POST /v1/email/messages is een plat payload, dus elke personalization wordt een eigen verzending (of één batch-entry).
| Wat het doet | SendGrid | Bird |
|---|---|---|
| Afzender | from.email | from |
| Ontvangers | personalizations[].to / cc / bcc | to / cc / bcc (arrays) |
| Onderwerp | subject | subject |
| Inhoud | content[] (type + value) | html / text (minstens één) |
| Reply-to | reply_to / reply_to_list | reply_to (array) |
| Aangepaste headers | headers | headers (string → string object) |
| Filterbare labels | categories | tags: {name, value}-paren |
| Roundtrip-context | custom_args | metadata: willekeurig JSON |
| Opgeslagen template | template_id + dynamic_template_data | template + template.parameters |
| Planning | send_at | scheduled_at |
| Open-/kliktracking | tracking_settings | track_opens / track_clicks (standaard true) |
| IP-pool | ip_pool_name | ip_pool_id (ipp_... of ipp_shared) |
| Categorie | (geen) | category: marketing (standaard) of transactional |
Onze veldlimieten en standaardwaarden (aantal ontvangers, tag- en metadatalimieten) staan in E-mail verzenden.
Opmerkingen bij het porten:
- categories zijn kale strings. Onze tags zijn paren. Een categorie als "welcome" wordt {"name": "category", "value": "welcome"}. Kies een stabiele name zodat je dashboards filteren zoals je SendGrid-statistieken deden.
- custom_args werden meegestuurd bij elk event. Ons metadata werkt op dezelfde manier. We sturen je metadata (en tags) mee bij elk webhook-event naast email_id/recipient_id, zodat je handlers je context terugkrijgen zonder een extra lookup.
- Dynamic templates worden opgeslagen templates. template_id plus dynamic_template_data worden template (aangeduid met ID of slug) plus template.parameters in dezelfde verzendaanroep. Zie verzenden met een template. send_at vertaalt rechtstreeks naar scheduled_at.
- Bijlagen porten rechtstreeks. SendGrids attachments (base64 content, type, filename, content_id voor inline) vertalen veld voor veld naar onze attachments-array.
- Uitschrijfgroepen (asm) zijn niet als concept te porten: wij regelen list-unsubscribe op categorie-niveau, dus marketing-mail krijgt automatisch suppressiebewuste uitschrijfafhandeling.
Exporteer suppressies
SendGrid verdeelt suppressies over meerdere endpoints; exporteer ze allemaal en voer ze door de importloop:
- GET /v3/suppression/bounces
- GET /v3/suppression/spam_reports
- GET /v3/suppression/unsubscribes (globale uitschrijvingen)
- GET /v3/asm/groups/{group_id}/suppressions voor elke uitschrijfgroep die je wilt meenemen
Vertaal webhook-events
| Resultaat | SendGrid Event Webhook | Bird |
|---|---|---|
| Geaccepteerd/verwerkt | processed | email.accepted → email.processed |
| Afgeleverd | delivered | email.delivered |
| Tijdelijke fout | deferred | email.deferred |
| Permanente bounce | bounce | email.bounced / email.out_of_band_bounce |
| Spamklacht | spamreport | email.complained |
| Geblokkeerd/onderdrukt | dropped | email.rejected |
| Open | open | email.opened |
| Klik | click | email.clicked |
| Uitschrijving | unsubscribe / group_unsubscribe | email.unsubscribed / email.list_unsubscribed |
De equivalentie dropped ↔ email.rejected is de belangrijkste om te testen: net als SendGrid melden wij onderdrukte ontvangers zichtbaar (status rejected, rejection_reason: recipient_suppressed) in plaats van ze stilletjes te laten vallen, dus je auditlogica port schoon mee.
Verificatie verandert meer dan alleen de eventnamen: SendGrids Event Webhook tekent met een ECDSA-publickey, terwijl wij tekenen volgens het Standard Webhooks HMAC-schema. Vervang je verificatiecode door het recept in Webhooks & events. SendGrid batcht events ook in JSON-arrays. Wij leveren één event per request.
Overschakelen
Werk domeinen & DNS en de sandbox-rooktest in de hoofdgids door. Beide zijn provideronafhankelijk.
Volgende stappen
- Verzenddomeinen: registratie, verificatielevenscyclus en de DNS-records die je omzet
- Webhooks & events: endpointconfiguratie en Standard Webhooks-verificatie
- Testsandbox: rooktest de nieuwe integratie vóór de overschakeling
- Suppressies: controleer je geïmporteerde lijst en hoe wij die vanaf hier onderhouden
Gerelateerde bronnen
Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.
Bekijk de gidsGetting started with emailOntdek de mogelijkheidEmailVolg het leerpadBuild your first integrationImplementatiegidsSend your first email
Probeer de oefening en ontvang een implementatieoverzicht