Migrar do SendGrid
Esta página mapeia o payload do v3 Mail Send, as listas de supressão e o Event Webhook do SendGrid para Bird. Siga o guia principal de migração na ordem indicada e use estes mapeamentos para os passos 1, 3 e 4.
Entregue isto ao seu agente
Cole isto no Claude Code, Cursor ou Codex. O agente percorre esta página em relação ao seu próprio repositório, usando qualquer superfície Bird que já tenha: o servidor MCP se estiver conectado, o CLI se estiver instalado e autenticado.
Exemplo de código
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.Mapear a chamada de envio
O POST /v3/mail/send do SendGrid encapsula destinatários em um array personalizations. Nosso POST /v1/email/messages é um payload plano, então cada personalização se torna um envio próprio (ou uma entrada de lote).
| O que faz | SendGrid | Bird |
|---|---|---|
| Remetente | from.email | from |
| Destinatários | personalizations[].to / cc / bcc | to / cc / bcc (arrays) |
| Assunto | subject | subject |
| Corpo | content[] (type + value) | html / text (pelo menos um) |
| Reply-to | reply_to / reply_to_list | reply_to (array) |
| Cabeçalhos personalizados | headers | headers (objeto string → string) |
| Rótulos filtráveis | categories | tags: pares {name, value} |
| Contexto de ida e volta | custom_args | metadata: JSON arbitrário |
| Template armazenado | template_id + dynamic_template_data | template + template.parameters |
| Agendamento | send_at | scheduled_at |
| Rastreamento de abertura/clique | tracking_settings | track_opens / track_clicks (padrão true) |
| Pool de IPs | ip_pool_name | ip_pool_id (ipp_... ou ipp_shared) |
| Categoria | (nenhum) | category: marketing (padrão) ou transactional |
Os limites e valores padrão dos campos (contagem de destinatários, limites de tags e metadados) estão em Enviando e-mail.
Notas de portabilidade:
- categories são strings simples. Nossas tags são pares. Uma categoria como "welcome" se torna {"name": "category", "value": "welcome"}. Escolha um name estável para que seus dashboards filtrem da mesma forma que suas estatísticas no SendGrid.
- custom_args eram ecoados em todo evento. Nosso metadata funciona da mesma forma. Ecoamos seus metadata (e tags) em cada evento de webhook junto com email_id/recipient_id, para que seus handlers recuperem o contexto sem uma consulta extra.
- Templates dinâmicos migram para templates armazenados. template_id mais dynamic_template_data se tornam template (referenciado por ID ou slug) mais template.parameters na mesma chamada de envio. Veja enviando com um template. send_at mapeia diretamente para scheduled_at.
- Anexos migram diretamente. O attachments do SendGrid (base64 content, type, filename, content_id para inline) mapeia para nosso array attachments campo a campo.
- Grupos de cancelamento de inscrição (asm) não migram como conceito: tratamos list-unsubscribe no nível da categoria, então e-mails marketing recebem tratamento de cancelamento com reconhecimento de supressão automaticamente.
Exportar supressões
O SendGrid divide supressões em vários endpoints; exporte cada um e processe-os pelo loop de importação:
- GET /v3/suppression/bounces
- GET /v3/suppression/spam_reports
- GET /v3/suppression/unsubscribes (cancelamentos globais)
- GET /v3/asm/groups/{group_id}/suppressions para cada grupo de cancelamento que você deseja migrar
Traduzir eventos de webhook
| Resultado | SendGrid Event Webhook | Bird |
|---|---|---|
| Aceito/processado | processed | email.accepted → email.processed |
| Entregue | delivered | email.delivered |
| Falha temporária | deferred | email.deferred |
| Bounce permanente | bounce | email.bounced / email.out_of_band_bounce |
| Reclamação de spam | spamreport | email.complained |
| Bloqueado/suprimido | dropped | email.rejected |
| Abertura | open | email.opened |
| Clique | click | email.clicked |
| Cancelamento | unsubscribe / group_unsubscribe | email.unsubscribed / email.list_unsubscribed |
A equivalência dropped ↔ email.rejected é a que você deve testar: assim como o SendGrid, reportamos destinatários suprimidos de forma visível (status rejected, rejection_reason: recipient_suppressed) em vez de descartá-los silenciosamente, então sua lógica de auditoria migra sem problemas.
A verificação muda mais do que os nomes dos eventos: o Event Webhook do SendGrid assina com uma chave pública ECDSA, enquanto nós assinamos conforme o esquema HMAC do Standard Webhooks. Substitua seu código de verificação pela receita em Webhooks e eventos. O SendGrid também agrupa eventos em arrays JSON. Nós entregamos um evento por solicitação.
Fazer a virada
Siga domínios e DNS e o teste de fumaça no sandbox no guia principal. Ambos são independentes de provedor.
Próximos passos
- Domínios de envio: registro, ciclo de vida da verificação e os registros DNS que você está redirecionando
- Webhooks e eventos: configuração do endpoint e verificação Standard Webhooks
- Sandbox de teste: teste de fumaça da nova integração antes da virada
- Supressões: confirme sua lista importada e como a mantemos daqui em diante
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.
Assista ao guiaGetting started with emailExplore a funcionalidadeEmailSiga o percurso de aprendizagemBuild your first integrationGuia de implementaçãoSend your first email
Experimente na prática e obtenha um resumo de implementação