Migrasi dari provider lain

Gunakan panduan ini untuk memindahkan email produksi dari provider lain. Petakan send request, publikasikan DNS record, impor daftar supresi, terjemahkan event webhook, dan uji integrasi sebelum mengarahkan traffic produksi ke Bird.

Checklist migrasi:

Petakan send call Anda ke POST /v1/email/messages
Arahkan ulang sending domain dan DNS Anda
Impor daftar supresi Anda
Alihkan webhook ke kosakata event kami
Verifikasi terhadap mail sandbox sebelum cutover

Langkah 1, 3, dan 4 bergantung pada provider yang Anda tinggalkan. Panduan provider Anda memuat pemetaan payload field per field, cara mengekspor daftar supresi, dan tabel terjemahan nama event webhook.

1. Petakan send call

Kami memiliki satu endpoint single-send, POST /v1/email/messages. Anda membuat payload JSON datar (tanpa wrapper personalizations, tanpa MIME assembly) dengan from, array to/cc/bcc, subject, html dan/atau text, daftar reply_to opsional, dan headers untuk custom email header. Pengiriman yang berhasil mengembalikan 202 Accepted dengan message ID berawalan em_. Hasil pengiriman tiba secara asinkron melalui webhook dan read endpoint. Payload lengkap, dengan setiap batas field dan default, ada di Mengirim email. Pemetaan field per field dari payload Anda saat ini ada di panduan provider Anda. Jika aplikasi Anda mengirim melalui SMTP saat ini, Anda mungkin tidak perlu memindahkan call sama sekali: kami menerima pengiriman SMTP ke pipeline yang sama, sehingga langkah ini menjadi sekadar penggantian kredensial.

Gunakan tags untuk dimensi filter di daftar pesan, analitik, dan rollup dashboard. Gunakan metadata untuk konteks terstruktur yang disimpan Bird pada pesan, dikembalikan pada pembacaan API, dan di-echo pada event webhook. Lihat Tags vs metadata untuk batasannya.

Sebelum Anda memindahkan kode, perhatikan perbedaan berikut:

Penjadwalan, stored template, dan attachment semuanya bisa dipindahkan. Gunakan scheduled_at untuk pengiriman terjadwal. Gunakan template alih-alih konten inline untuk stored template. Petakan file ke array attachments.
Penerima yang disupresi ditolak secara eksplisit. Alamat yang disupresi tetap mendapat recipient_id dan muncul di daftar penerima pesan dengan status rejected dan event email.rejected (rejection_reason: recipient_suppressed), tidak pernah diabaikan secara diam-diam. Bahkan ketika semua penerima disupresi, request tetap diterima dengan 202. Setiap penerima dikembalikan sebagai ditolak. Lihat Suppressions.
Atur category: "transactional" untuk mail operasional. Pengiriman default-nya adalah marketing, dan kategori ini mengontrol kebijakan supresi: marketing memblokir berdasarkan complaint dan unsubscribe, transactional tetap mengirim melewatinya. Newsletter dan kampanye sudah ditangani dengan benar oleh default. Tandai tanda terima, reset password, dan mail operasional serupa dengan transactional agar tidak diblokir oleh unsubscribe.

2. Arahkan ulang domain dan DNS

Daftarkan setiap sending domain dengan POST /v1/email/domains atau di Email > Domains, lalu publikasikan record dari dns_records. DKIM, return-path CNAME, dan kebijakan DMARC menjadi syarat pengiriman. Record DMARC yang sudah ada, termasuk di parent domain, sudah memenuhi syarat. Tracking CNAME hanya menjadi syarat untuk pelacakan open dan click bermerek. Sending domains membahas record, siklus verifikasi, dan model regional. Gunakan DNS record splitter jika provider Anda memerlukan nilai DKIM yang dipisah, dan generator kebijakan DMARC jika Anda memerlukan kebijakan.

Satu record yang biasanya diminta provider lain justru sengaja tidak ada: Anda tidak mempublikasikan record SPF di apex domain Anda. SPF dievaluasi terhadap domain envelope-from, yang diarahkan return-path CNAME ke kami, sehingga SPF lolos dan selaras tanpa menyentuh apex Anda. Jika provider lama Anda meminta Anda menambahkan include: ke record SPF apex, biarkan tetap ada selama transisi dan hapus setelah cutover. Record itu tidak membantu maupun mengganggu mail yang dikirim melalui kami, dan menghapusnya membebaskan satu dari 10 DNS lookup yang diizinkan SPF apex. Penjelasan lengkap ada di DKIM, SPF & DMARC.

Anda dapat mempublikasikan record kami sementara record provider lama masih aktif. Record DKIM menggunakan selector milik kami. Return-path dan tracking CNAME adalah hostname baru yang Anda pilih, dan record DMARC Anda yang sudah ada memenuhi syarat apa adanya. Kedua provider melakukan autentikasi berdampingan sampai Anda siap mengalihkan traffic. Status domain bersifat regional, jadi daftarkan domain di setiap region tempat Anda mengirim.

3. Impor daftar supresi

Pindahkan daftar supresi Anda sebelum mengirim traffic produksi melalui kami. Jika tidak, pengiriman pertama Anda menuju alamat yang sudah bounce atau complaint di provider lama, yang merusak reputasi yang sedang Anda jaga.

Ekspor daftar dari provider Anda saat ini (panduan provider Anda memuat endpoint pastinya), lalu tambahkan setiap alamat di sini dengan POST /v1/email/suppressions:

Contoh kode

while read -r address; do
  curl -s -X POST https://us1.platform.bird.com/v1/email/suppressions \
    -H "Authorization: Bearer $BIRD_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"email\": \"$address\"}"
done < suppressions.txt

Dua hal yang perlu diketahui tentang jalur impor ini:

Anda mengimpor satu alamat per request. API supresi adalah CRUD entri tunggal, jadi daftar besar berarti melakukan loop atas alamat yang diekspor. Call ini idempoten (201 untuk record baru, 200 dengan record yang sudah ada jika alamat sudah disupresi secara manual), jadi menjalankan ulang impor yang belum selesai aman dilakukan.
Alamat yang diimpor mendapat reason: manual, applies_to: all, yang memblokir setiap kategori, termasuk transaksional. Ini lebih ketat daripada record complaint native, yang hanya memblokir pengiriman non-transaksional, jadi jika Anda memerlukan perilaku berbasis kategori untuk alamat tertentu, lihat taksonomi alasan di Suppressions.

Ke depannya Anda tidak perlu mengelola bounce sendiri: kami otomatis menyupresi hard bounce dan complaint, mengirimkan email_suppression.created agar sistem Anda dapat mencerminkan daftar supresi. Unsubscribe dicatat sebagai preferensi yang dinyatakan, dan dicerminkan melalui email.unsubscribed dan email.list_unsubscribed, bukan melalui event supresi.

4. Alihkan webhook

Daftarkan endpoint dengan POST /v1/webhooks dan subscribe ke daftar tipe event secara eksplisit. Nama event kami mengikuti resource.action: email.accepted → email.processed → email.delivered pada jalur sukses, dengan email.deferred, email.bounced, email.complained, email.rejected, email.opened, email.clicked, dan pasangan unsubscribe untuk sisanya. Terjemahan nama event dari kosakata provider Anda saat ini ada di panduan provider Anda. Skema payload per event ada di referensi events.

Korelasi berpindah dengan bersih. Setiap event memiliki identifier email_id, recipient_id, dan workspace_id. Event juga meng-echo tags dan metadata dari send request. Ini mengembalikan konteks yang sebelumnya provider lama Anda berikan melalui payload echo tanpa lookup tambahan. Masukkan ID internal Anda di metadata pada saat pengiriman dan baca langsung dari setiap event.

Kami menandatangani pengiriman sesuai spesifikasi Standard Webhooks, menggunakan tiga header: webhook-id, webhook-timestamp, dan webhook-signature, dengan HMAC-SHA256 atas {id}.{timestamp}.{raw body}. Jika Anda sudah memverifikasi pengiriman Standard Webhooks dari platform lain, kode verifikasi yang sama persis berfungsi di sini. Jika belum, resep verifikasi, jadwal coba lagi, dan tooling replay ada di Webhooks & events. Pengiriman bersifat at-least-once dan tidak berurutan, jadi deduplikasi berdasarkan webhook-id dan urutkan berdasarkan timestamp payload, disiplin yang sama yang seharusnya sudah dimiliki handler Anda saat ini.

5. Verifikasi di sandbox sebelum cutover

Sebelum memindahkan traffic produksi, jalankan integrasi lengkap Anda (send call yang sudah dipindahkan, webhook handler, pencerminan supresi) terhadap mail sandbox. Pengiriman sandbox menuju magic address di messagebird.dev dan melewati pipeline produksi nyata: 202 yang sama, urutan event yang sama, pengiriman webhook bertanda tangan yang sama, tanpa pernah mencapai inbox atau memengaruhi reputasi Anda.

Smoke test minimum sebelum cutover:

Kirim ke delivered@messagebird.dev dan pastikan handler Anda memproses email.accepted → email.processed → email.delivered.
Kirim ke bounce@messagebird.dev dan pastikan penanganan bounce Anda aktif pada email.bounced (bounce simulasi tidak menulis ke daftar supresi Anda, jadi alamat tetap dapat digunakan ulang).
Kirim ke suppressed@messagebird.dev dan pastikan Anda menangani email.accepted diikuti email.rejected, tanpa email.processed atau event pengiriman setelahnya. Itulah bentuk yang dihasilkan setiap penerima tersupresi di produksi; detail rejection_reason: recipient_suppressed ada di record penerima dan event API.
Kirim pesan category: "marketing" dan konfirmasi kategori muncul sesuai yang Anda harapkan pada pembacaan pesan.

Gunakan subaddressing +label (bounce+cutover-test@messagebird.dev) untuk mengorelasikan test case. Alamat lengkap muncul di event Anda. Setelah smoke test lolos, alihkan traffic. Arahkan aplikasi Anda ke kami, dan biarkan DNS provider lama tetap ada sampai domain Anda di sini menunjukkan capabilities.sending terverifikasi. Pantau jam-jam pertama pengiriman nyata di dashboard dan webhook stream Anda.

Migrasi dari provider tertentu

SendGrid: personalizations → payload datar, categories/custom_args → tags/metadata, kesetaraan dropped ↔ email.rejected
Mailgun: parameter o:*/v:*/h:* → field first-class, ekspor bounces/complaints/unsubscribes
Amazon SES: SendEmail v2 → satu endpoint, configuration set → flag pelacakan per pesan, SNS → signed webhook
Resend: bentuk payload hampir identik, Svix-signed webhook → Standard Webhooks
Postmark: penerima dipisah koma → array, dump supresi per stream, unsigned webhook → signed
Brevo: objek alamat → alamat biasa, dua blocklist terpisah untuk diekspor, params → template.parameters
MailerSend: lima daftar supresi di mana yang temporer tetap tertinggal, personalization → parameter per pengiriman
Mailjet: array Messages → satu payload datar, EventPayload → metadata, ekspor blocklist
Mandrill: wrapper message dan body auth → payload datar dan bearer auth, ekspor rejection blacklist

Langkah selanjutnya

Mengirim email: payload pengiriman lengkap, tags vs metadata, model async 202
Sending domains: pendaftaran, siklus verifikasi, setup multi-region
DKIM, SPF & DMARC: apa yang dibuktikan setiap record, dan mengapa SPF apex tidak diperlukan
Suppressions: alasan, kategori, dan API pengelolaan
Webhooks & events: setup endpoint, verifikasi Standard Webhooks, coba lagi dan replay
Events: skema payload per event
Testing sandbox: daftar lengkap magic address dan panduan langkah demi langkah
Referensi API: skema request dan response untuk send endpoint

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.

Tonton panduannyaGetting started with email Jelajahi kemampuannyaEmail Ikuti jalur pembelajaranBuild your first integration Panduan implementasiSend your first email

Coba praktiknya dan dapatkan ringkasan implementasi