Migrasi dari SparkPost

Gunakan panduan ini untuk memindahkan email keluar dari SparkPost ke Bird. Ikuti daftar periksa migrasi utama, menggunakan pemetaan di bawah untuk integrasi HTTP atau SMTP Anda.

Sebelum memulai

Anda memerlukan akses ke akun dan subakun SparkPost, DNS domain pengirim, konfigurasi aplikasi, dan handler webhook. Siapkan workspace Bird dan kunci API di region pilihan Anda. Impor opt-out juga memerlukan izin tulis preferences pada kunci tersebut.

Inventarisasi pengirim, template, snippet, daftar penerima, supresi, pengiriman terjadwal, IP pool, dan webhook. Sertakan SDK, mail adapter framework, background job, dan alur email masuk. Catat ID resource baru saat Anda membuatnya; ID dan kredensial SparkPost tidak berfungsi di Bird. Gunakan SDK Bird saat mengganti klien SparkPost, dan tinjau retry, timeout, dan paginasinya.

Jika Anda menggunakan subakun SparkPost, hubungi kami sebelum memilih tata letak workspace. Konfirmasi workspace yang tersedia, izin, resource bersama, dan alur kerja penyediaan tenant. Kunci API workspace tidak dapat berpindah tenant dengan X-MSYS-SUBACCOUNT. Pertahankan tenant yang ditangguhkan dan pembatasan pengiriman khusus tenant selama migrasi.

Konfirmasi bahwa kuota paket dan batas laju Bird Anda mencakup volume pengiriman, jumlah resource, dan lalu lintas puncak Anda.

Daftarkan domain pengirim Anda lebih awal. Pertahankan DNS SparkPost yang berfungsi dan pilih hostname return-path serta tracking terpisah jika diperlukan. Jika pendaftaran melaporkan konflik kepemilikan, hubungi dukungan sebelum menghapus domain aktif.

IP Dedicated: Hubungi kami atau tim akun Anda sebelum migrasi. Minta kami untuk mengonfirmasi apakah IP SparkPost Anda yang ada dapat dipindahkan ke Bird dan sepakati pengaturan pool, waktu, dan warmup yang diperlukan. Sertakan region akun, alamat IP, nama pool, dan volume pengiriman Anda. Pertahankan IP Anda saat ini tetap aktif hingga rencana migrasi dikonfirmasi.

Konfirmasi pemilihan pool dan allowlist IP atau hostname penerima sebelum cutover. Membeli IP tidak mengubah pool default. IP yang baru dibeli dapat mengirim kelebihan melalui infrastruktur bersama selama warmup, yang penting jika penerima hanya menerima email dari IP tertentu.

Serahkan ini ke agen Anda

Tempel ini ke agen coding Anda di repositori aplikasi:

Help me migrate my SparkPost email integration to Bird.
1. Use an existing Bird MCP connection or signed-in CLI. Otherwise follow https://bird.com/docs/ai/set-up-your-agent.md. Append .md to Bird docs URLs to read Markdown.
2. Read https://bird.com/docs/guides/email/migrate/sparkpost.md and https://bird.com/docs/guides/email/migrate.md. Make a read-only inventory of my SparkPost call sites, SDKs, resource IDs, configured URLs, sending domains, and scheduled jobs before editing. Never print API keys.
3. Propose workspace and region mappings. If subaccounts, dedicated IPs, or domain ownership conflicts need a migration plan, use the available Bird tools to open a human email support ticket and return its ID. For CLI usage, read https://bird.com/docs/cli/reference/support-tickets-create.md. Wait for the agreed plan before moving those resources.
4. Follow https://bird.com/docs/guides/email/sending-domains.md; preserve working DNS and show me proposed records. Ask before DNS changes or paid provisioning.
5. Port sending, templates, and webhooks using this guide. Preserve recipient privacy, personalization, and categories. Export suppressions with scope and type; show me the handling before importing or changing preferences.
6. Test using https://bird.com/docs/guides/email/testing-sandbox.md. Show me results and unresolved differences, including tracking, signatures, and correlation.
7. Ask for explicit approval before production cutover. Keep a rollback path; get separate approval before retiring SparkPost resources or credentials.

Petakan panggilan kirim

Ganti POST /api/v1/transmissions dengan POST /v1/email/messages, atau POST /v1/email/batches untuk pesan independen. Ikhtisar API SparkPost mencantumkan host regional dan autentikasinya. Bird menggunakan https://us1.platform.bird.com atau https://eu1.platform.bird.com, sesuai region kunci API Anda, dengan Authorization: Bearer $BIRD_API_KEY.

Satu transmisi SparkPost dapat menghasilkan email terpisah yang dipersonalisasi untuk setiap penerimanya. Bird membagikan konten dan parameter ke seluruh penerima dalam satu pengiriman. Gunakan pesan terpisah untuk setiap personalisasi, dan kelompokkan secara opsional dalam satu batch. Pengiriman hanya-To tetap ditujukan secara individual; periksa header yang terlihat saat menambahkan salinan Cc/Bcc.

Petakan field transmisi SparkPost:

Untuk salinan To/Cc/Bcc dari satu email, bangun ulang grup penerima satu kali. Alamat yang ditampilkan SparkPost bisa berbeda dari penerima pengiriman; to, cc, dan bcc Bird masing-masing menambahkan penerima pengiriman. Menyalin header CC SparkPost ke cc setiap pesan yang diperluas dapat mengirim salinan duplikat. Verifikasi header yang terlihat dan jumlah penerima sebelum beralih.

Periksa batas field pengiriman, penjadwalan, dan aturan lampiran. Perbarui ID inline-image dan referensi cid: yang sesuai agar memenuhi aturan Bird. Konfigurasikan return path dan tracking domain pada domain.

Field pengiriman HTTP Bird tidak mencakup content.email_rfc822, content.amp_html, atau options.inline_css SparkPost. Bangun ulang pesan mentah dengan field yang didukung, sediakan fallback HTML/text untuk AMP, dan inline CSS sebelum mengirimkan HTML. SMTP mem-parse dan membangun ulang bagian pesan yang didukung; validasi MIME yang diterima jika Anda bergantung pada struktur persisnya. Parameter MIME lampiran seperti calendar method atau text charset tidak dipertahankan.

Untuk pesan API terjadwal, Bird mengunci versi template, bahasa, dan parameter saat menerima permintaan. Pengeditan template selanjutnya tidak memperbarui pesan tersebut. Untuk mengubahnya, batalkan pesan terjadwal sebelum pemrosesan dimulai, lalu kirimkan penggantinya. Simpan sekumpulan ID pesan Bird jika Anda perlu menggantikan pembatalan berbasis kampanye SparkPost.

Atur BIRD_API_KEY ke kunci Bird Anda. Contoh sandbox ini tidak memerlukan domain terverifikasi dan tidak menjangkau inbox nyata. Untuk kunci EU, gunakan https://eu1.platform.bird.com:

curl --fail-with-body https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "onboarding@messagebird.dev",
    "to": ["delivered@messagebird.dev"],
    "subject": "Your receipt",
    "text": "Thanks for your order, {{ first_name }}.",
    "parameters": {"first_name": "Alex"},
    "category": "transactional",
    "metadata": {"order_id": "order_123"},
    "tags": [{"name": "mailstream", "value": "receipts"}]
  }'

Harapkan 202 Accepted dan sebuah ID pesan em_. Simpan ID tersebut dan ikuti hasil penerima melalui event. Penerimaan tidak menjamin pengiriman: penerima yang disupresi dapat diterima lalu kemudian ditolak. Perbarui parsing respons, penanganan error, dan coba lagi yang idempoten bersama panggilan pengiriman.

Untuk batch, baca array data dan simpan ID setiap pesan terhadap catatan pengiriman Anda sendiri. Bird memvalidasi batch sebelum mengantre: satu pesan yang tidak valid dapat menolak seluruh permintaan. Pecah transmisi besar agar sesuai dengan batas batch, dan ikuti aturan coba lagi Bird ketika respons ambigu.

Berikan setiap permintaan atau potongan batch kunci idempotensi stabil tersendiri. Jendela replay Bird berbeda dari SparkPost; simpan catatan pengiriman aplikasi Anda melampaui jendela tersebut untuk mencegah duplikasi selama cutover atau rollback.

Pindahkan pengirim SMTP

Gunakan pengaturan koneksi SMTP Bird, username bird, dan kunci API dengan pengiriman email diaktifkan. Periksa region, TLS, dan konfigurasi kunci.

Konversi opsi X-MSYS-API SparkPost sebelum menghapus header tersebut. Atur default kategori, tag, pelacakan, dan pool di konfigurasi SMTP Bird. Pengaturan tersebut berlaku per kunci API; gunakan kunci terkonfigurasi terpisah atau HTTP jika pengaturan berbeda antarpesan. Gunakan HTTP untuk metadata per pesan atau parameter template.

Masukkan setiap penerima pengiriman ke dalam envelope SMTP, penerima yang terlihat ke header MIME To/Cc, dan penerima Bcc hanya ke dalam envelope. Inventarisasi X-MSYS-API.archive secara terpisah: salinan arsip SparkPost mempertahankan URL pelacakan penerima asli, jadi Bcc biasa tidak setara. Validasi penggantinya sebelum mengalihkan alur tersebut.

Salin pengaturan pelacakan efektif Anda secara eksplisit: kunci SMTP Bird yang belum dikonfigurasi mengaktifkan pelacakan buka dan klik, sementara default SparkPost bervariasi per akun. Atur kategori juga: Bird SMTP default ke transaksional dan HTTP inline ke marketing. Pengirim newsletter memerlukan marketing di kedua jalur.

Untuk coba lagi SMTP, gunakan kembali kunci idempotensi, envelope, dan byte MIME yang sama persis. Meregenerasi Date, Message-ID, atau boundary MIME mengubah payload dan dapat mencegah percobaan ulang yang aman.

Konversi template

Ekspor versi yang benar-benar Anda kirim melalui Templates API SparkPost: daftar dengan GET /api/v1/templates?draft=false, lalu ambil konten dengan GET /api/v1/templates/{id}?draft=false. Simpan draf secara terpisah jika diperlukan. Sertakan template yang dibagikan dengan subaccount dan snippet yang direferensikan dalam inventaris.

Bahasa template SparkPost dan sintaks Liquid Bird berbeda. Konversi kondisional, loop, nilai default, dan nilai bersarang. Selesaikan override penerima dan metadata yang digunakan untuk rendering menjadi parameter eksplisit. Misalnya, {{ if ... }} menjadi {% if ... %}. Sintaks {{ name }} yang sama saja tidak menjamin kompatibilitas.

Ekspansi snippet sebelum menerbitkan; Liquid Bird tidak mendukung include atau render. Untuk template tersimpan, ganti referensi eksternal seperti {{ user.name }} dengan parameter datar seperti {{ user_name }}. Jika Anda menyisipkan HTML dinamis melalui parameter SparkPost, render di aplikasi Anda dan kirimkan body yang sudah lengkap tanpa parameters inline; nilai parameter HTML biasa di-escape.

Buat, pratinjau, dan publikasikan template Bird, lalu ikuti mengirim dengan template. Bawa pengirim efektif, Reply-To, dan header kustom dari SparkPost ke dalam permintaan pengiriman; template Bird menyediakan kontennya.

Untuk Liquid inline, sertakan parameters, bahkan {}; jika dihilangkan, token tetap tidak berubah. Verifikasi nilai yang hilang, escaping, dan URL.

Ganti placeholder berhenti berlangganan dengan {{ bird.unsubscribe_url }}. Bird menyediakan header berhenti berlangganan marketing; hapus header List-Unsubscribe dan List-Unsubscribe-Post kustom dari pengiriman marketing untuk menghindari penolakan 422.

Tautan berhenti berlangganan Bird mengeluarkan alamat dari email marketing di seluruh workspace. Tautan ini tidak menyediakan opsi keluar per daftar tertentu. Periksa perilaku ini jika integrasi SparkPost Anda menawarkan langganan terpisah.

Pindahkan daftar penerima

Ekspor setiap daftar penerima tersimpan dengan GET /api/v1/recipient-lists/{id}?show_recipients=true untuk menyertakan keanggotaan dan personalisasi. Buat audiens tujuan dan daftarkan properti kontak sebelum mengimpor. Tinjau setiap hasil impor dan rekonsiliasi jumlah keanggotaan.

Properti kontak melekat pada kontak di seluruh audiensnya. Jika alamat yang sama memiliki data substitusi berbeda di beberapa daftar SparkPost, rekonsiliasi nilai tersebut sebelum mengimpor agar tidak tertimpa. Properti kontak Bird bertipe skalar; simpan personalisasi per daftar atau terstruktur di aplikasi Anda jika tidak dapat direpresentasikan dengan aman.

Gunakan broadcast jika template yang dipublikasikan dapat diisi dari properti kontak. Keanggotaan audiens ditentukan saat pengiriman dimulai, dan batas pengiriman serta konkurensi broadcast berlaku. Gunakan pesan batch independen untuk parameter khusus permintaan atau snapshot penerima tetap. Validasi penanganan izin dan supresi sebelum mengaktifkan daftar yang dimigrasikan.

Ekspor supresi

Ekspor sebelum pengiriman produksi. Mulai dengan GET /api/v1/suppression-list?cursor=initial&types=transactional,non_transactional,open_tracking, lalu ikuti paginasi hingga selesai. Simpan catatan lengkap, termasuk tipe, sumber, ID daftar, subaccount, dan timestamp. Gunakan X-MSYS-SUBACCOUNT: 0 untuk akun utama dan setiap ID subaccount untuk daftarnya sendiri. Lihat Suppression List API SparkPost.

Klasifikasikan catatan berdasarkan tipe, sumber, dan cakupan sebelum menggunakan loop impor dari panduan utama. POST /v1/email/suppressions Bird menerima email dan membuat pemblokiran manual di seluruh workspace pada kedua kategori:

• Alamat yang diblokir dari penerimaan email: impor alamat yang harus diblokir di semua kategori. Simpan ekspor asli untuk rekonsiliasi; catatan yang diimpor membawa alasan manual Bird.
• Opt-out marketing seluruh akun: gunakan POST /v1/preferences dengan channel: "email", alamat di handle, status: "revoked", dan coverage: "non_transactional". Atur source: "sparkpost-migration" untuk rekonsiliasi. Tinjau preferensi Bird yang sudah ada terlebih dahulu dan pertahankan pembatasan yang lebih ketat; periksa applied dan preferensi yang dikembalikan setelah setiap penulisan.
• Pembatasan khusus daftar atau khusus transaksional: pertahankan cakupannya dalam kelayakan pengiriman aplikasi Anda. Preferensi email Bird berlaku untuk seluruh channel dan tidak dapat merepresentasikan cakupan ini. Supresi manual juga dapat memblokir reset kata sandi. Tahan traffic yang terpengaruh sampai Anda memverifikasi penggantinya.
• Opt-out pelacakan buka: atur track_opens: false untuk pesan independen, selain pembatasan pengiriman apa pun. Untuk SMTP, gunakan kunci dengan pelacakan buka dinonaktifkan atau gunakan HTTP untuk kontrol per pesan.

Permintaan preferensi di atas mencatat pembatasan pada saat impor. Simpan stempel waktu asli SparkPost dalam ekspor Anda dan rekonsiliasi persetujuan yang lebih baru sebelum menulis. Rekonsiliasi catatan yang diimpor dan penulisan yang gagal, lalu uji kedua kategori. Sinkronkan opt-out dan supresi baru selama kedua penyedia masih mengirim. Terus terapkan opt-out dari email SparkPost yang sudah terkirim sebelumnya ke Bird setelah cutover. Lihat Supresi untuk penanganan bounce dan komplain bawaan.

Terjemahkan event webhook

SparkPost mengirim event webhook dalam batch di dalam wrapper msys. Bird mengirimkan satu event per permintaan dengan type, timestamp, dan data. Daftarkan endpoint Bird dengan langganan event eksplisit dan verifikasi tanda tangan. Pertahankan handler SparkPost tetap aktif untuk traffic yang tersisa.

Pengiriman langsung melalui API dan SMTP menghasilkan email.accepted sebelum pemrosesan. Broadcast mencatat penerimaan di event API dan log email, tetapi tidak mengirim webhook tersebut. policy_rejection, generation_failure, dan generation_rejection milik SparkPost dipetakan ke email.rejected; periksa rejection_reason. Deduplikasi open secara terpisah saat menghitung engagement unik.

Gunakan data.email_id dan data.recipient_id untuk korelasi Bird, dan sertakan identifier Anda sendiri di metadata. Ganti penanganan batch-ID SparkPost dengan aturan deduplikasi dan pengurutan webhook Bird. Baca detail bounce sebelum memutuskan apakah suatu alamat harus disupresi; klasifikasi bounce membedakan kegagalan alamat permanen dari kegagalan sementara atau kebijakan.

Pertahankan riwayat pelaporan

Ekspor riwayat event SparkPost dan laporan agregat yang Anda butuhkan sebelum jendela retensinya berakhir. Ikuti paginasi event hingga selesai dan simpan ID provider, cakupan akun/subakun, timestamp, dan filter pelaporan. Terus kumpulkan event yang terlambat selama periode tumpang tindih, dan simpan riwayat SparkPost di arsip terpisah.

Simpan baseline untuk setiap aliran pengiriman. Bandingkan populasi penerima dan jendela pelaporan yang sesuai, lalu periksa definisi metrik: penerimaan provider, pengiriman ke server penerima, engagement unik, dan open yang di-prefetch adalah ukuran yang berbeda. Nama metrik yang sama saja tidak menjamin tingkat yang sebanding.

Migrasikan email masuk secara terpisah

Jika Anda menggunakan relay webhook SparkPost, ikuti Menerima email untuk alur tersebut. Webhook email.received dari Bird menyediakan inbound_message_id; ambil body, lampiran, atau MIME mentah melalui API alih-alih mengharapkan pesan lengkap di dalam webhook. Uji handler Anda dengan alamat penerusan Bird, lalu siapkan penerimaan domain sebelum mengubah rekaman MX. Verifikasi perutean balasan setelah perubahan DNS dan arsipkan konten yang Anda butuhkan melampaui periode retensi penerimaan Bird.

Verifikasi dan cutover

1. Verifikasi kemampuan pengiriman setiap domain. Jalankan smoke test sandbox dan kasus komplain. Pastikan event bertanda tangan sampai ke handler Anda, berkorelasi dengan pesan yang benar, dan tangani pengiriman duplikat. Event sandbox tidak membuktikan pengiriman ke inbox, rendering, atau pelacakan.
2. Kirim dari domain terverifikasi Anda ke inbox nyata yang terkontrol. Periksa personalisasi, visibilitas To/Cc/Bcc, lampiran, autentikasi, dan pelacakan. Uji berhenti berlangganan: email marketing harus berhenti sementara email transaksional yang memenuhi syarat tetap berlanjut. Uji secara terpisah bahwa pemblokiran semua kategori menolak keduanya. Pisahkan pemeriksaan ini dari hasil sandbox yang disimulasikan.
3. Tetapkan pengiriman terjadwal yang tertunda ke satu penyedia. Kosongkan atau batalkan pengiriman asli sebelum membuatnya ulang di tempat lain. Simpan catatan aplikasi tentang penyedia mana yang menerima setiap pengiriman logis agar percobaan ulang atau rollback tidak mengirim salinan kedua.
4. Pindahkan sebagian traffic secara terkontrol dan pantau metrik pengiriman serta pemrosesan webhook. Untuk IP khusus, ikuti rencana migrasi yang disepakati dengan tim kami, termasuk warmup jika diperlukan. Tingkatkan traffic setelah hasil yang diamati memenuhi persyaratan pengiriman Anda.
5. Jika validasi gagal, jeda traffic Bird yang terpengaruh dan arahkan pengiriman baru melalui jalur SparkPost yang dipertahankan dengan opt-out terkini diterapkan. Rekonsiliasi pengiriman yang ambigu sebelum mencoba ulang. Nonaktifkan kredensial, webhook, dan DNS lama setelah antrean dan event terlambat diperhitungkan; pertahankan tautan pelacakan dan berhenti berlangganan lama tetap berfungsi untuk email yang sudah terkirim sebelumnya.

Jika autentikasi gagal, periksa bearer token Bird dan region. Jika impor preferensi mengembalikan 403, periksa izin tulis preferences pada kunci sebelum melanjutkan. Jika personalisasi dirender secara tidak benar, periksa konversi Liquid dan parameter. Jika email transaksional ditolak secara tidak terduga, periksa supresi manual yang diimpor. Gunakan log email dan detail event untuk memverifikasi setiap koreksi.

Langkah selanjutnya

• Mengirim email: field payload, personalisasi, dan hasil asinkron
• Template email: pratinjau, publikasi, dan dukungan Liquid
• Supresi: alasan supresi dan pengelolaan
• Webhook dan event: tanda tangan, percobaan ulang, dan pemutaran ulang