Sign inGet started

Migracja z SendGrid

Ta strona mapuje payload v3 Mail Send, listy suppressions i Event Webhook z SendGrid na Bird. Postępuj zgodnie z głównym przewodnikiem migracji po kolei i korzystaj z tych mapowań w krokach 1, 3 i 4.

Przekaż to swojemu agentowi

Wklej to do Claude Code, Cursora lub Codex. Agent przetworzy tę stronę na tle Twojego repozytorium, korzystając z dowolnego interfejsu Bird, który już ma: serwera MCP, jeśli jest podłączony, lub CLI, jeśli jest zainstalowany i zalogowany.
Przykład kodu
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.

Zmapuj wywołanie wysyłki

POST /v3/mail/send w SendGrid umieszcza odbiorców w tablicy personalizations. Nasz POST /v1/email/messages to płaski payload, więc każda personalizacja staje się osobną wysyłką (lub jednym wpisem wsadowym).
FunkcjaSendGridBird
Nadawcafrom.emailfrom
Odbiorcypersonalizations[].to / cc / bccto / cc / bcc (tablice)
Tematsubjectsubject
Treśćcontent[] (type + value)html / text (co najmniej jedno)
Reply-toreply_to / reply_to_listreply_to (tablica)
Własne nagłówkiheadersheaders (obiekt string → string)
Etykiety filtrującecategoriestags: pary {name, value}
Kontekst zwrotnycustom_argsmetadata: dowolny JSON
Zapisany szablontemplate_id + dynamic_template_datatemplate + template.parameters
Planowaniesend_atscheduled_at
Śledzenie otwarć/kliknięćtracking_settingstrack_opens / track_clicks (domyślnie true)
Pula IPip_pool_nameip_pool_id (ipp_... lub ipp_shared)
Kategoria(brak)category: marketing (domyślnie) lub transactional
Limity pól i wartości domyślne (liczba odbiorców, limity tagów i metadanych) znajdziesz w Wysyłanie e-maili.
Uwagi do migracji:
  • categories to zwykłe stringi. Nasze tagi to pary. Kategoria taka jak "welcome" staje się {"name": "category", "value": "welcome"}. Wybierz stały name, aby Twoje dashboardy filtrowały tak samo jak statystyki w SendGrid.
  • custom_args były zwracane w każdym zdarzeniu. Nasz metadata działa tak samo. Zwracamy Twoje metadata (i tags) w każdym zdarzeniu webhooka obok email_id/recipient_id, więc Twoje handlery odzyskują kontekst bez dodatkowego zapytania.
  • Szablony dynamiczne przenoszą się na zapisane szablony. template_id plus dynamic_template_data stają się template (referencja po ID lub slugu) plus template.parameters w tym samym wywołaniu wysyłki. Zobacz wysyłanie z szablonem. send_at mapuje się bezpośrednio na scheduled_at.
  • Załączniki przenoszą się bezpośrednio. attachments w SendGrid (base64 content, type, filename, content_id dla inline) mapują się na naszą tablicę attachments pole po polu.
  • Grupy wypisów (asm) nie przenoszą się jako koncept: obsługujemy list-unsubscribe na poziomie kategorii, więc poczta marketing automatycznie otrzymuje obsługę wypisów uwzględniającą suppression.

Eksport suppressions

SendGrid rozdziela suppression między endpointy; wyeksportuj każdy i przepuść go przez pętlę importu:
  • GET /v3/suppression/bounces
  • GET /v3/suppression/spam_reports
  • GET /v3/suppression/unsubscribes (globalne wypisy)
  • GET /v3/asm/groups/{group_id}/suppressions dla każdej grupy wypisów, którą chcesz przenieść

Przetłumacz zdarzenia webhooka

WynikSendGrid Event WebhookBird
Zaakceptowano/przetworzoneprocessedemail.acceptedemail.processed
Dostarczonodeliveredemail.delivered
Tymczasowa awariadeferredemail.deferred
Trwałe odrzuceniebounceemail.bounced / email.out_of_band_bounce
Zgłoszenie spamuspamreportemail.complained
Zablokowano/wstrzymanodroppedemail.rejected
Otwarcieopenemail.opened
Kliknięcieclickemail.clicked
Wypisunsubscribe / group_unsubscribeemail.unsubscribed / email.list_unsubscribed
Równoważność droppedemail.rejected to element wymagający testów: tak jak SendGrid, raportujemy wstrzymanych odbiorców jawnie (status rejected, rejection_reason: recipient_suppressed) zamiast po cichu ich pomijać, więc Twoja logika audytu przenosi się bez zmian.
Weryfikacja zmienia się bardziej niż same nazwy zdarzeń: Event Webhook w SendGrid podpisuje kluczem publicznym ECDSA, a my podpisujemy zgodnie ze schematem HMAC Standard Webhooks. Zamień swój kod weryfikacji na przepis z Webhooks & events. SendGrid grupuje też zdarzenia w tablice JSON. My dostarczamy jedno zdarzenie na żądanie.

Przełączenie

Przejdź przez domeny i DNS oraz test dymny w sandboxie w głównym przewodniku. Oba kroki są niezależne od dostawcy.

Następne kroki

  • Domeny wysyłkowe: rejestracja, cykl życia weryfikacji i rekordy DNS, które przekierowujesz
  • Webhooks i zdarzenia: konfiguracja endpointu i weryfikacja Standard Webhooks
  • Sandbox testowy: przetestuj nową integrację przed przełączeniem
  • Suppression: potwierdź zaimportowaną listę i sposób, w jaki ją utrzymujemy od tego momentu