Sign inGet Started

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:

  1. Petakan send call Anda ke POST /v1/email/messages
  2. Arahkan ulang sending domain dan DNS Anda
  3. Impor daftar supresi Anda
  4. Alihkan webhook ke kosakata event kami
  5. 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 dan dikembalikan pada pembacaan API. Event webhook juga dapat membawa konteks ini, tetapi event unsubscribe dapat mengembalikan nilai null. 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 Supresi.
  • 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 Supresi.

Selanjutnya, hard bounce membuat supresi workspace dan memicu email_suppression.created, terlepas dari atribusi Brand. Complaint tanpa atribusi Brand yang andal juga membuat supresi workspace dan memicu email_suppression.created. Complaint yang teratribusi ke Brand dicatat sebagai preferensi yang dilindungi. Unsubscribe dicatat sebagai preferensi. Subscribe juga ke event preferensi, bahkan untuk workspace dengan satu Brand, agar sistem Anda mencerminkan opt-out ini dan pemberian izin berikutnya. Event tingkat pesan email.complained, email.unsubscribed, dan email.list_unsubscribed tetap tersedia. Lihat Email events untuk perbedaannya.

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.

Korelasikan event pesan keluar menggunakan email_id dan workspace_id; event siklus hidup penerima juga membawa recipient_id. Simpan pemetaan pesan ke pelanggan tersebut saat Anda mengirim. Perlakukan tags dan metadata sebagai konteks tambahan jika ada: email.unsubscribed dan email.list_unsubscribed dari link unsubscribe Bird mengembalikan nilai null untuk pengiriman individual, meskipun pengiriman tersebut menyertakannya. Event unsubscribe broadcast juga dapat mengembalikan null jika konteks tersebut tidak tersedia.

Gunakan preference.revoked, preference.granted, dan preference.deleted sebagai sinyal untuk memperbarui mirror preferensi Anda. Event ini mengidentifikasi preference_id dan transition_id, beserta cakupan channel, handle, Brand, sender, dan topik; event ini tidak membawa message ID atau metadata pengiriman. timestamp pada event ini adalah waktu berlakunya pernyataan, bukan versi record. Complaint yang tertunda dapat mencabut pemberian izin bulk yang lebih baru, dan perubahan yang berbeda dapat memiliki timestamp yang sama. Jangan menentukan status atau cakupan saat ini dengan mengurutkan event atau memperlakukan transition_id sebagai urutan.

Inisialisasi dan pertahankan mirror preferensi yang lengkap dengan urutan berikut:

  1. Subscribe ke event preferensi dan simpan notifikasi yang masuk secara tahan lama sebelum memulai pembacaan awal.
  2. Isi mirror dari setiap halaman daftar preferensi workspace, tanpa filter channel, handle, atau Brand. Langkah ini menemukan opt-out yang sudah ada tetapi belum pernah menghasilkan notifikasi untuk endpoint Anda. Simpan ID, channel, handle, Brand, sender, dan cakupan topik setiap record.
  3. Proses notifikasi yang disimpan dan yang baru dengan mengambil preferensi saat ini dan membaca daftar untuk channel dan handle yang terdampak di setiap halaman. Bandingkan cakupan untuk menangani penghapusan dan pembuatan ulang dengan ID berbeda. Rekonsiliasi juga daftar workspace lengkap tanpa filter secara berkala, termasuk penerima yang tidak ada di notifikasi atau di mirror lokal Anda.

Hasil pembacaan dapat tertinggal dari perubahan: coba lagi saat terjadi error sementara atau saat state hilang atau lebih lama dari yang diharapkan. Pembacaan yang gagal atau tidak lengkap tidak boleh menghapus blokir lokal. Hapus record yang sudah dihapus hanya setelah memastikan record itu memang tidak ada; pertahankan preferensi dan supresi lain yang independen. Mirror ini konvergen seiring waktu dan tidak menggantikan pemeriksaan saat pengiriman oleh Bird.

email_suppression.created mengidentifikasi penambahan berdasarkan suppression_id, workspace_id, dan email. Tidak ada event penghapusan supresi pelanggan. Untuk menemukan penghapusan yang dilakukan di dashboard atau API, baca daftar supresi workspace secara berkala di setiap halaman dan rekonsiliasi berdasarkan ID supresi. Jangan hapus record setelah pemindaian yang gagal atau tidak lengkap; pastikan record yang hilang pada pembacaan berikutnya sebelum menghapusnya. Pisahkan record supresi dari preferensi agar menghapus satu blokir tidak menghapus blokir lain.

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 percobaan ulang, dan tooling replay ada di Webhooks & events. Pengiriman bersifat at-least-once dan tidak berurutan, jadi deduplikasi berdasarkan webhook-id. Gunakan timestamp event pesan untuk menampilkan kronologi pesan; gunakan rekonsiliasi state saat ini untuk preferensi dan supresi seperti dijelaskan di atas.

5. Verifikasi di sandbox sebelum cutover

Sebelum memindahkan traffic produksi, uji send call yang sudah dipindahkan dan handler event pesan 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.

Sinyal sandbox tidak menulis record supresi atau preferensi complaint. Uji mirror Anda secara terpisah dengan payload email_suppression.created, preference.revoked, preference.granted, dan preference.deleted yang representatif dari kontrak event webhook, termasuk dua Brand yang berbagi penerima yang sama. Sertakan kasus berikut:

  • Opt-out yang tidak berubah sudah ada sebelum pendaftaran webhook. Inventaris awal tanpa filter menemukannya tanpa notifikasi; inventaris berkala juga menemukan record yang tidak ada di mirror lokal Anda.
  • Unsubscribe dari pengiriman individual memiliki tags dan metadata bernilai null; pemetaan pesan yang Anda simpan tetap mengidentifikasi pelanggan.
  • Complaint tiba setelah pemberian izin bulk yang lebih baru, atau opt-out semua kategori yang lebih lama memperluas perlindungan complaint tanpa memajukan timestamp berlakunya. Kirim event dalam urutan terbalik dan pastikan rekonsiliasi mempertahankan status dicabut dan cakupan saat ini.
  • Preferensi dihapus lalu dibuat ulang, atau supresi manual dihapus di dashboard. Rekonsiliasi hanya menghapus record yang dipastikan tidak ada dan mempertahankan blokir yang tidak terkait.
  • Pembaruan gagal atau untuk sementara mengembalikan state yang lebih lama. Handler Anda mencoba lagi, dan rekonsiliasi berkala memperbaiki mirror tanpa menghapus blokir pada pembacaan yang gagal.

Smoke test minimum sebelum cutover:

  1. Kirim ke delivered@messagebird.dev dan pastikan handler Anda memproses email.accepted → email.processed → email.delivered.
  2. 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).
  3. 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 yang disupresi di produksi; detail rejection_reason: recipient_suppressed ada di record penerima dan event API.
  4. 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

  • SparkPost: transmission dan SMTP, konversi template, supresi bercakupan, dan event webhook
  • 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
  • Supresi: alasan, kategori, dan API pengelolaan
  • Webhooks & events: setup endpoint, verifikasi Standard Webhooks, percobaan ulang 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