Migrare da SendGrid
Questa pagina mappa il payload v3 Mail Send, le liste di soppressione e l'Event Webhook di SendGrid su Bird. Segui la guida principale alla migrazione nell'ordine indicato e usa queste corrispondenze per i passaggi 1, 3 e 4.
Passa questo al tuo agente
Incolla questo in Claude Code, Cursor o Codex. L'agente lavora su questa pagina nel tuo repository, usando qualsiasi superficie Bird di cui dispone: il server MCP se è collegato, la CLI se è installata e autenticata.
Esempio di codice
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.Mappare la chiamata di invio
Il POST /v3/mail/send di SendGrid racchiude i destinatari in un array personalizations. Il nostro POST /v1/email/messages è un payload piatto, quindi ogni personalizzazione diventa un invio a sé (o una voce batch).
| Funzione | SendGrid | Bird |
|---|---|---|
| Mittente | from.email | from |
| Destinatari | personalizations[].to / cc / bcc | to / cc / bcc (array) |
| Oggetto | subject | subject |
| Corpo | content[] (type + value) | html / text (almeno uno) |
| Reply-to | reply_to / reply_to_list | reply_to (array) |
| Header personalizzati | headers | headers (oggetto string → string) |
| Etichette filtrabili | categories | tags: coppie {name, value} |
| Contesto round-trip | custom_args | metadata: JSON arbitrario |
| Template salvato | template_id + dynamic_template_data | template + template.parameters |
| Pianificazione | send_at | scheduled_at |
| Tracciamento aperture/clic | tracking_settings | track_opens / track_clicks (default true) |
| Pool IP | ip_pool_name | ip_pool_id (ipp_... o ipp_shared) |
| Categoria | (nessuno) | category: marketing (default) o transactional |
Limiti e valori predefiniti dei campi (numero di destinatari, limiti di tag e metadati) si trovano in Invio di email.
Note sulla migrazione:
- Le categories sono stringhe semplici. I nostri tag sono coppie. Una categoria come "welcome" diventa {"name": "category", "value": "welcome"}. Scegli un name stabile in modo che le tue dashboard filtrino come facevano le statistiche di SendGrid.
- I custom_args venivano inclusi in ogni evento. Il nostro metadata funziona allo stesso modo. Includiamo i tuoi metadata (e tags) in ogni evento webhook insieme a email_id/recipient_id, così i tuoi handler recuperano il contesto senza una ricerca aggiuntiva.
- I template dinamici diventano template salvati. template_id più dynamic_template_data diventano template (referenziato per ID o slug) più template.parameters nella stessa chiamata di invio. Vedi invio con un template. send_at corrisponde direttamente a scheduled_at.
- Gli allegati si portano direttamente. I campi attachments di SendGrid (base64 content, type, filename, content_id per inline) corrispondono campo per campo al nostro array attachments.
- I gruppi di disiscrizione (asm) non si portano come concetto: gestiamo il list-unsubscribe a livello di categoria, quindi la mail marketing riceve automaticamente la gestione della disiscrizione con supporto alla soppressione.
Esportare le soppressioni
SendGrid distribuisce le soppressioni su diversi endpoint; esporta ciascuno e passalo attraverso il ciclo di importazione:
- GET /v3/suppression/bounces
- GET /v3/suppression/spam_reports
- GET /v3/suppression/unsubscribes (disiscrizioni globali)
- GET /v3/asm/groups/{group_id}/suppressions per ogni gruppo di disiscrizione che vuoi trasferire
Tradurre gli eventi webhook
| Esito | SendGrid Event Webhook | Bird |
|---|---|---|
| Accettato/elaborato | processed | email.accepted → email.processed |
| Consegnato | delivered | email.delivered |
| Errore temporaneo | deferred | email.deferred |
| Bounce permanente | bounce | email.bounced / email.out_of_band_bounce |
| Segnalazione spam | spamreport | email.complained |
| Bloccato/soppresso | dropped | email.rejected |
| Apertura | open | email.opened |
| Clic | click | email.clicked |
| Disiscrizione | unsubscribe / group_unsubscribe | email.unsubscribed / email.list_unsubscribed |
L'equivalenza dropped ↔ email.rejected è quella da verificare: come SendGrid, segnaliamo i destinatari soppressi in modo visibile (status rejected, rejection_reason: recipient_suppressed) anziché scartarli silenziosamente, quindi la tua logica di audit si porta senza problemi.
La verifica cambia più dei semplici nomi degli eventi: l'Event Webhook di SendGrid firma con una chiave pubblica ECDSA, mentre noi firmiamo secondo lo schema HMAC di Standard Webhooks. Sostituisci il tuo codice di verifica con la procedura in Webhook ed eventi. SendGrid inoltre raggruppa gli eventi in array JSON. Noi consegniamo un evento per richiesta.
Passaggio in produzione
Segui domini e DNS e il test di fumo in sandbox nella guida principale. Entrambi sono indipendenti dal provider.
Passaggi successivi
- Domini di invio: registrazione, ciclo di vita della verifica e i record DNS che stai reindirizzando
- Webhook ed eventi: configurazione dell'endpoint e verifica Standard Webhooks
- Sandbox di test: testa la nuova integrazione prima del passaggio in produzione
- Soppressioni: verifica la lista importata e come la manteniamo da qui in avanti
Risorse correlate
Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.
Guarda la guidaGetting started with emailEsplora la funzionalitàEmailSegui il percorso di apprendimentoBuild your first integrationGuida all'implementazioneSend your first email
Prova l'esercitazione e ottieni un brief di implementazione