Migrer depuis SendGrid
Cette page fait correspondre le payload v3 Mail Send, les listes de suppression et l'Event Webhook de SendGrid à Bird. Suivez le guide de migration principal dans l'ordre et utilisez ces correspondances pour les étapes 1, 3 et 4.
Transmettez ceci à votre agent
Collez ceci dans Claude Code, Cursor ou Codex. L'agent parcourt cette page en s'appuyant sur votre propre dépôt, en utilisant la surface Bird dont il dispose déjà : le serveur MCP s'il est connecté, le CLI s'il est installé et authentifié.
Exemple de code
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.Faire correspondre l'appel d'envoi
Le POST /v3/mail/send de SendGrid encapsule les destinataires dans un tableau personalizations. Notre POST /v1/email/messages est un payload plat : chaque personnalisation devient son propre envoi (ou une entrée de lot).
| Fonction | SendGrid | Bird |
|---|---|---|
| Expéditeur | from.email | from |
| Destinataires | personalizations[].to / cc / bcc | to / cc / bcc (tableaux) |
| Objet | subject | subject |
| Corps | content[] (type + value) | html / text (au moins un) |
| Reply-to | reply_to / reply_to_list | reply_to (tableau) |
| En-têtes personnalisés | headers | headers (objet string → string) |
| Libellés filtrables | categories | tags : paires {name, value} |
| Contexte aller-retour | custom_args | metadata : JSON arbitraire |
| Template enregistré | template_id + dynamic_template_data | template + template.parameters |
| Planification | send_at | scheduled_at |
| Suivi ouverture/clic | tracking_settings | track_opens / track_clicks (défaut true) |
| Pool d'IP | ip_pool_name | ip_pool_id (ipp_... ou ipp_shared) |
| Catégorie | (aucun) | category : marketing (défaut) ou transactional |
Les limites et valeurs par défaut de nos champs (nombre de destinataires, limites de tags et de métadonnées) se trouvent dans Envoyer un e-mail.
Notes de portage :
- Les categories sont des chaînes simples. Nos tags sont des paires. Une catégorie comme "welcome" devient {"name": "category", "value": "welcome"}. Choisissez un name stable pour que vos tableaux de bord filtrent comme le faisaient vos statistiques SendGrid.
- Les custom_args étaient renvoyés dans chaque événement. Notre metadata fonctionne de la même façon. Nous renvoyons vos metadata (et tags) dans chaque événement webhook aux côtés de email_id/recipient_id, afin que vos handlers récupèrent votre contexte sans requête supplémentaire.
- Les templates dynamiques se portent en templates enregistrés. template_id plus dynamic_template_data deviennent template (référencé par ID ou slug) plus template.parameters dans le même appel d'envoi. Voir envoyer avec un template. send_at correspond directement à scheduled_at.
- Les pièces jointes se portent directement. Les attachments de SendGrid (base64 content, type, filename, content_id pour inline) correspondent à notre tableau attachments champ par champ.
- Les groupes de désabonnement (asm) ne se portent pas en tant que concept : nous gérons le list-unsubscribe au niveau de la catégorie, de sorte que le courrier marketing bénéficie automatiquement d'une gestion du désabonnement tenant compte des suppressions.
Exporter les suppressions
SendGrid répartit les suppressions entre plusieurs endpoints ; exportez chacun et passez-les dans la boucle d'import :
- GET /v3/suppression/bounces
- GET /v3/suppression/spam_reports
- GET /v3/suppression/unsubscribes (désabonnements globaux)
- GET /v3/asm/groups/{group_id}/suppressions pour chaque groupe de désabonnement que vous souhaitez conserver
Traduire les événements webhook
| Résultat | SendGrid Event Webhook | Bird |
|---|---|---|
| Accepté/traité | processed | email.accepted → email.processed |
| Distribué | delivered | email.delivered |
| Échec temporaire | deferred | email.deferred |
| Rebond permanent | bounce | email.bounced / email.out_of_band_bounce |
| Plainte spam | spamreport | email.complained |
| Bloqué/supprimé | dropped | email.rejected |
| Ouverture | open | email.opened |
| Clic | click | email.clicked |
| Désabonnement | unsubscribe / group_unsubscribe | email.unsubscribed / email.list_unsubscribed |
L'équivalence dropped ↔ email.rejected est celle à tester : comme SendGrid, nous signalons les destinataires supprimés de façon visible (statut rejected, rejection_reason: recipient_suppressed) au lieu de les ignorer silencieusement, de sorte que votre logique d'audit se porte sans difficulté.
La vérification change davantage que les noms d'événements : l'Event Webhook de SendGrid signe avec une clé publique ECDSA, tandis que nous signons selon le schéma HMAC de Standard Webhooks. Remplacez votre code de vérification par la recette décrite dans Webhooks & events. SendGrid regroupe aussi les événements en tableaux JSON. Nous livrons un événement par requête.
Basculer
Parcourez domaines et DNS et le test de fumée en sandbox dans le guide principal. Les deux sont indépendants du fournisseur.
Étapes suivantes
- Domaines d'envoi : enregistrement, cycle de vie de la vérification et enregistrements DNS que vous redirigez
- Webhooks & events : configuration de l'endpoint et vérification Standard Webhooks
- Sandbox de test : testez la nouvelle intégration avant la bascule
- Suppressions : vérifiez votre liste importée et la façon dont nous la maintenons ensuite
Ressources associées
Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.
Regarder le guideGetting started with emailExplorer la fonctionnalitéEmailSuivre le parcours d'apprentissageBuild your first integrationGuide d'implémentationSend your first email
Essayez la pratique et obtenez un guide d'implémentation