Event email

Kami mengirimkan event setiap penerima bergerak melalui proses pengiriman. Satu pengiriman ke tiga alamat menghasilkan tiga aliran independen, dikorelasikan berdasarkan email_id dan recipient_id. Halaman ini mendefinisikan tipe event email. Lihat Webhook untuk tanda tangan, percobaan ulang, urutan, dan replay.

Setiap penerima dimulai dari email.accepted, lalu email.processed. Penerima broadcast adalah pesannya sendiri, jadi ia mendapat email.accepted sendiri juga, meskipun hanya di event API dan log email, bukan sebagai webhook. Dari sana pesan diterima oleh server penerima (email.delivered), ditangguhkan dan dicoba ulang (email.deferred, yang berakhir sebagai delivered atau bounced), ditolak oleh server penerima (email.bounced), atau tidak pernah mendapat percobaan pengiriman sama sekali (email.rejected). Setelah pengiriman, aliran dapat berlanjut dengan email.out_of_band_bounce, email.complained, email.opened, email.clicked, email.unsubscribed, dan email.list_unsubscribed.

Setiap penerima berakhir tepat pada satu status terminal, delivered, bounced, complained, atau rejected, yang dikembalikan sebagai status per penerima dari GET /v1/email/messages/{message_id}/recipients. Event interaksi tidak pernah mengubahnya: penerima yang membuka pesan tetap berstatus delivered. Laporan bounce terlambat mengubahnya, karena server penerima menarik kembali penerimaan yang sudah diberikan, sehingga penerima berpindah dari delivered ke bounced. Pesan secara keseluruhan memiliki status gabungan dan hitungan per status di GET /v1/email/messages/{message_id}.

Event tiba sebagai envelope tiga field yang digunakan semua webhook: type, timestamp (kapan event terjadi, RFC 3339), dan objek data yang spesifik per tipe.

{
  "type": "email.delivered",
  "timestamp": "2026-07-23T14:51:47.107Z",
  "data": {
    "email_id": "em_01ky7qc398fmxraqtxn604zeq9",
    "recipient_id": "er_01ky7qc398fmwsc96nt6anrbqs",
    "workspace_id": "ws_01ky7m21hjffh9s8kq76gyb1xf",
    "recipient": "delivered@messagebird.dev",
    "recipient_role": "to",
    "tags": [{ "name": "category", "value": "welcome" }],
    "metadata": { "order_id": "ord_123" },
    "broadcast_id": null
  }
}

Setiap event keluar mencakup email_id, recipient_id, workspace_id, alamat recipient, dan envelope recipient_role-nya (to, cc, atau bcc). Event juga menyertakan tags dan metadata dari permintaan pengiriman agar Anda dapat mengorelasikan event dengan catatan Anda. Setiap nilai opsional bernilai null jika pengiriman tidak memilikinya, termasuk broadcast_id: field ini menamai broadcast yang menjadi bagian dari pengiriman, sehingga Anda dapat mengelompokkan event broadcast tanpa mencari setiap pengiriman satu per satu, dan bernilai null pada pengiriman tanpa broadcast di belakangnya. Satu kasus melaporkan null untuk pengiriman yang memiliki broadcast: tautan berhenti berlangganan dari email yang dikirim sebelum kami menambahkan field tersebut tidak menamai broadcast, sehingga opt-out melalui tautan tersebut melaporkan null pada email.unsubscribed dan email.list_unsubscribed baik ada maupun tidak ada broadcast yang mengirim email tersebut. Perlakukan null pada kedua event tersebut sebagai tidak konklusif, atau Anda akan menghitung kurang opt-out broadcast. broadcast_id sampai kepada Anda hanya melalui webhook: event API di bawah mengembalikan setiap event tanpa field tersebut. Tipe event menambahkan field yang dijelaskan di bagian siklus hidup, interaksi, supresi, dan inbound.

Event yang sama dapat di-query setelahnya dari GET /v1/email/messages/{message_id}/events, di mana setiap event juga memiliki id (prefiks ev_) dan occurred_at. Gunakan untuk backfill, replay, atau rekonsiliasi terhadap apa yang diterima endpoint Anda. Beberapa field hanya sampai kepada Anda melalui API tersebut, bukan melalui webhook; deskripsi event yang relevan mengidentifikasi masing-masing.

Kami telah menerima pengiriman dan mulai menyiapkan pengiriman. Dipicu satu kali per penerima yang diminta dan merupakan event pertama dalam aliran tersebut. Penerima broadcast juga mendapatkannya, karena setiap penerima adalah pesannya sendiri, tetapi dicatat bukan dikirim: baca dari event API atau log email, bukan dari endpoint webhook Anda. Payload: hanya basis identitas.

Pesan telah dibuat dan diantrikan untuk pengiriman ke server email penerima. Payload: hanya basis identitas melalui webhook; event API menambahkan mailbox_provider dan mailbox_provider_region, klasifikasi sistem email penerima (misalnya gmail, NA), ada jika bisa ditentukan dan null jika tidak. Membandingkan timestamp event ini dengan email.accepted memberikan waktu pemrosesan kami pada satu pengiriman. Broadcast tidak memiliki interval seperti itu: penerimaan dan pemrosesannya membawa waktu dispatch yang sama, sehingga kedua timestamp cocok alih-alih mengapit pemrosesan apa pun, dan penerimaan hanya sampai kepada Anda melalui event API, sebagai occurred_at.

Server email penerima menerima pesan dan bertanggung jawab atasnya. Event ini tidak menetapkan penempatan inbox atau pembacaan. Inbox Insights menyediakan estimasi penempatan sampel; event open dan click mencatat permintaan pelacakan. Payload: hanya basis identitas melalui webhook; event API menambahkan sending_ip, alamat asal pengiriman pesan, yang penting saat masalah deliverability melacak satu IP, ditambah mailbox_provider dan mailbox_provider_region.

Kegagalan sementara: server penerima meminta kami mencoba lagi nanti (kotak surat penuh, greylisting, pembatasan laju permintaan). Kami mencoba ulang secara otomatis, dan penerima akhirnya berakhir sebagai email.delivered atau email.bounced, sehingga event ini bersifat informasional bukan terminal, dan seorang penerima bisa ditangguhkan beberapa kali terlebih dahulu. Payload: bounce_type, bounce_class, defer_reason (alasan yang diberikan server), dan sending_ip melalui webhook; event API menambahkan mailbox_provider dan mailbox_provider_region.

Kegagalan permanen pada waktu SMTP: server penerima menolak pesan, dan status terminal penerima menjadi bounced. Payload: bounce_type (lihat tabel klasifikasi), bounce_class, bounce_code (kode balasan SMTP, misalnya 550), bounce_description (alasan yang diberikan server), dan sending_ip melalui webhook; event API menambahkan mailbox_provider dan mailbox_provider_region. Hard bounce menyupresi alamat tersebut.

Bounce terlambat: server penerima menerima pesan pada waktu SMTP lalu mengirimkan laporan bounce setelahnya. Klasifikasinya sama dengan email.bounced (bounce_type, bounce_class, bounce_code, bounce_description, sending_ip melalui webhook; mailbox_provider dan mailbox_provider_region dari event API). Ketika laporan diklasifikasikan sebagai bounce (kelas apa pun dalam tabel), server telah menarik kembali penerimaannya sebelumnya, sehingga penerima berpindah dari delivered ke bounced. Laporan yang kelasnya tidak ada dalam tabel, seperti balasan otomatis, dicatat di timeline dan tidak mengubah status. Hard out-of-band bounce juga menyupresi alamat tersebut.

Penerima tidak pernah sampai ke server email jarak jauh, sehingga tidak ada percobaan pengiriman. Itulah yang membedakan penolakan dari bounce, di mana server penerimalah yang mengatakan tidak. Payload: rejection_reason, juga ada di catatan penerima, salah satu dari:

Event API juga menambahkan mailbox_provider dan mailbox_provider_region ketika sistem email penerima dapat diklasifikasikan sebelum penolakan.

Penerima menandai pesan sebagai spam dan penyedia kotak surat melaporkannya kembali melalui feedback loop-nya. Keluhan tiba setelah pengiriman dan menetapkan status terminal ke complained. Payload: feedback_type, jenis laporan yang dikirim penyedia, seperti abuse atau fraud, dan null jika penyedia tidak menyebutkan, ditambah mailbox_provider dan mailbox_provider_region dari event API. Keluhan menyupresi alamat untuk email marketing. Jaga tingkat keluhan Anda tetap rendah: penyedia membatasi pengirim yang mengumpulkan banyak laporan.

Piksel pelacakan di badan pesan dimuat. Payload: ip_address dan user_agent jika diketahui; event API menambahkan is_prefetched, country (ISO 3166-1 alpha-2, diturunkan dari IP klien), mailbox_provider, dan mailbox_provider_region. Periksa is_prefetched sebelum Anda menghitung open. Nilainya true ketika fitur privasi inbox mengambil piksel secara otomatis alih-alih seseorang membuka pesan, dan menghitung hal tersebut menggelembungkan tingkat open Anda. Pelacakan open dan click membahas instrumentasinya.

Penerima mengklik tautan terlacak. Payload: url (tautan yang diklik), ip_address, dan user_agent jika diketahui; event API menambahkan country, mailbox_provider, dan mailbox_provider_region. Klik umumnya merupakan sinyal interaksi yang lebih kuat daripada open karena proxy privasi dapat memuat piksel pelacakan secara otomatis.

Penerima menggunakan tautan berhenti berlangganan di badan pesan. Payload: hanya basis identitas melalui webhook; event API menambahkan mailbox_provider dan mailbox_provider_region. Mencatat preferensi opt-out yang memblokir email marketing. Tautan berhenti berlangganan membahas cara tautan masuk ke email Anda.

Penerima menggunakan tombol berhenti berlangganan satu klik yang dirender penyedia kotak surat di UI-nya sendiri, didorong oleh header List-Unsubscribe pesan. Payload: hanya basis identitas melalui webhook (ditambah mailbox_provider dan mailbox_provider_region dari event API); mekanismenya adalah tipe event itu sendiri, itulah mengapa ia terpisah dari email.unsubscribed. Juga mencatat preferensi opt-out yang memblokir email marketing.

Dua event mendeskripsikan pesan secara keseluruhan, bukan satu penerima, sehingga data-nya memiliki email_id, workspace_id, tags, dan metadata tetapi tanpa identitas penerima. Keduanya termasuk dalam pengiriman terjadwal.

Kami menerima pengiriman dengan scheduled_at di masa depan. Payload: basis level pesan ditambah scheduled_at. Ketika waktu tersebut tiba, siklus hidup per penerima dimulai dari email.accepted.

Pesan terjadwal dibatalkan sebelum terkirim, sehingga tidak menghasilkan event siklus hidup penerima sama sekali. Payload: hanya basis level pesan.

email.received mencakup email masuk. Dipicu saat kami menerima dan mengurai pesan inbound. Payload-nya mencakup inbound_message_id, addressing, subjek, dan hasil autentikasi. Setup, payload, dan API fetch-back ada di Menerima email. Mailbox memiliki keluarga email_mailbox.* sendiri di atasnya, dibahas di panduan mailbox.

bounce_class adalah klasifikasi bounce numerik yang disertakan pada email.bounced, email.out_of_band_bounce, dan email.deferred. Klasifikasi ini dirangkum menjadi bounce_type kasar dan mempertahankan kode detail, sehingga Anda tetap dapat membedakan kotak surat penuh dari kegagalan routing meskipun keduanya dilaporkan sebagai soft:

Kelas apa pun di luar daftar ini dipetakan ke undetermined. Hanya bounce hard yang menyupresi alamat; soft, block, admin, dan undetermined tidak, karena alamat tersebut mungkin masih dapat dikirimi.

Dua event menambahkan penerima ke daftar supresi workspace secara otomatis, dan keduanya memblokir email yang berbeda:

Hard bounce memblokir semuanya karena alamat itu sendiri sudah tidak ada. Keluhan memblokir marketing saja, karena seseorang yang melaporkan newsletter Anda sebagai spam masih membutuhkan reset kata sandi mereka.

email.unsubscribed dan email.list_unsubscribed memblokir email dengan cara yang sama seperti keluhan, yaitu hanya marketing, tetapi melalui catatan yang berbeda: alih-alih menambahkan supresi, keduanya mencatat opt-out penerima sebagai preferensi yang dinyatakan. Apa yang dilakukan opt-out membahas catatan tersebut secara lengkap.

Setiap penambahan memicu event email_suppression.created yang memiliki suppression_id, email yang disupresi, reason, dan workspace_id. Skema catatan lengkap dan cara mengelola entri secara manual ada di Panduan supresi.

Pengiriman berikutnya ke alamat yang disupresi ditolak langsung sebagai email.rejected dengan rejection_reason: "recipient_suppressed", dan tidak pernah dihitung terhadap deliverability Anda.