Migrasi dari SendGrid
Halaman ini memetakan payload v3 Mail Send, daftar supresi, dan Event Webhook SendGrid ke Bird. Ikuti panduan migrasi utama secara berurutan, dan gunakan pemetaan ini untuk langkah 1, 3, dan 4.
Berikan ini ke agent Anda
Tempel ini ke Claude Code, Cursor, atau Codex. Agent akan mengerjakan halaman ini terhadap repositori Anda sendiri, menggunakan permukaan Bird mana pun yang sudah tersedia: server MCP jika sudah terhubung, CLI jika sudah diinstal dan sudah login.
Contoh kode
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.Petakan panggilan pengiriman
POST /v3/mail/send SendGrid membungkus penerima dalam array personalizations. POST /v1/email/messages kami adalah payload datar, sehingga setiap personalization menjadi pengiriman tersendiri (atau satu entri batch).
| Fungsi | SendGrid | Bird |
|---|---|---|
| Pengirim | from.email | from |
| Penerima | personalizations[].to / cc / bcc | to / cc / bcc (array) |
| Subjek | subject | subject |
| Isi | content[] (type + value) | html / text (minimal satu) |
| Reply-to | reply_to / reply_to_list | reply_to (array) |
| Header kustom | headers | headers (objek string → string) |
| Label yang dapat difilter | categories | tags: pasangan {name, value} |
| Konteks round-trip | custom_args | metadata: JSON arbitrer |
| Template tersimpan | template_id + dynamic_template_data | template + template.parameters |
| Penjadwalan | send_at | scheduled_at |
| Pelacakan open/click | tracking_settings | track_opens / track_clicks (default true) |
| IP pool | ip_pool_name | ip_pool_id (ipp_... atau ipp_shared) |
| Kategori | (tidak ada) | category: marketing (default) atau transactional |
Batas field dan nilai default kami (jumlah penerima, batas tag dan metadata) ada di Mengirim email.
Catatan porting:
- categories adalah string biasa. Tag kami berupa pasangan. Kategori seperti "welcome" menjadi {"name": "category", "value": "welcome"}. Pilih name yang stabil agar dasbor Anda memfilter seperti cara statistik SendGrid Anda sebelumnya.
- custom_args di-echo di setiap event. metadata kami bekerja dengan cara yang sama. Kami meng-echo metadata (dan tags) Anda di setiap event webhook bersama email_id/recipient_id, sehingga handler Anda mendapatkan konteks kembali tanpa lookup tambahan.
- Template dinamis berpindah ke template tersimpan. template_id ditambah dynamic_template_data menjadi template (dirujuk berdasarkan ID atau slug) ditambah template.parameters pada panggilan pengiriman yang sama. Lihat mengirim dengan template. send_at dipetakan ke scheduled_at secara langsung.
- Lampiran berpindah langsung. attachments SendGrid (base64 content, type, filename, content_id untuk inline) dipetakan ke array attachments kami field per field.
- Grup berhenti berlangganan (asm) tidak berpindah sebagai konsep: kami menangani list-unsubscribe di tingkat kategori, sehingga email marketing mendapatkan penanganan berhenti berlangganan yang sadar supresi secara otomatis.
Ekspor supresi
SendGrid memecah supresi ke beberapa endpoint; ekspor masing-masing dan jalankan melalui loop impor:
- GET /v3/suppression/bounces
- GET /v3/suppression/spam_reports
- GET /v3/suppression/unsubscribes (berhenti berlangganan global)
- GET /v3/asm/groups/{group_id}/suppressions untuk setiap grup berhenti berlangganan yang ingin Anda bawa
Terjemahkan event webhook
| Hasil | SendGrid Event Webhook | Bird |
|---|---|---|
| Diterima/diproses | processed | email.accepted → email.processed |
| Terkirim | delivered | email.delivered |
| Kegagalan sementara | deferred | email.deferred |
| Bounce permanen | bounce | email.bounced / email.out_of_band_bounce |
| Keluhan spam | spamreport | email.complained |
| Diblokir/disupresi | dropped | email.rejected |
| Open | open | email.opened |
| Click | click | email.clicked |
| Berhenti berlangganan | unsubscribe / group_unsubscribe | email.unsubscribed / email.list_unsubscribed |
Kesetaraan dropped ↔ email.rejected adalah yang perlu Anda uji: seperti SendGrid, kami melaporkan penerima yang disupresi secara terlihat (status rejected, rejection_reason: recipient_suppressed) alih-alih membuangnya secara diam-diam, sehingga logika audit Anda berpindah dengan bersih.
Verifikasi berubah lebih dari sekadar nama event: Event Webhook SendGrid menandatangani dengan kunci publik ECDSA, sedangkan kami menandatangani sesuai skema HMAC Standard Webhooks. Ganti kode verifikasi Anda dengan resep di Webhooks & events. SendGrid juga mengelompokkan event ke dalam array JSON. Kami mengirim satu event per request.
Cutover
Kerjakan domain & DNS dan sandbox smoke test di panduan utama. Keduanya tidak bergantung pada provider.
Langkah selanjutnya
- Domain pengirim: registrasi, siklus hidup verifikasi, dan rekaman DNS yang akan Anda arahkan ulang
- Webhooks & events: pengaturan endpoint dan verifikasi Standard Webhooks
- Sandbox pengujian: smoke-test integrasi baru sebelum cutover
- Supresi: konfirmasi daftar yang telah diimpor dan cara kami memeliharanya selanjutnya
Sumber daya terkait
Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.
Tonton panduannyaGetting started with emailJelajahi kemampuannyaEmailIkuti jalur pembelajaranBuild your first integrationPanduan implementasiSend your first email
Coba praktiknya dan dapatkan ringkasan implementasi