Cek status dan daftar pesan

Setelah email diterima API dengan status queued, kamu bisa memantau perjalanannya sampai diterima server penerima — atau tahu persis kenapa gagal. kirim.id menyediakan dua endpoint: satu untuk detail sebuah pesan, satu lagi untuk daftar pesan dengan filter. Keduanya butuh scope send_email.

Detail satu pesan#

curl https://api.kirim.id/v1/messages/9b1c7e2a-5d0f-4b8e-9a51-3f0c2d6e7a10 \
  -H "Authorization: Bearer $KIRIM_API_KEY"

{
  "message_id": "9b1c7e2a-5d0f-4b8e-9a51-3f0c2d6e7a10",
  "status": "delivered",
  "failed_reason": null,
  "dispatched_at": "2026-09-22T03:04:07.000000Z",
  "channel": "api",
  "to": "[email protected]",
  "from": "[email protected]",
  "from_name": "Toko Rina",
  "reply_to": "[email protected]",
  "subject": "Invoice pesanan #1001",
  "metadata": {"order_id": "1001", "source": "woocommerce"},
  "attachments": [{"filename": "invoice-1001.pdf", "content_type": "application/pdf", "size": 48213}],
  "opened_at": "2026-09-22T03:10:12.000000Z",
  "clicked_at": null,
  "opens": 2,
  "clicks": 0,
  "created_at": "2026-09-22T03:04:05.000000Z",
  "events": [
    {"type": "delivered", "occurred_at": "2026-09-22T03:04:09.000000Z", "url": null},
    {"type": "open", "occurred_at": "2026-09-22T03:10:12.000000Z", "url": null}
  ]
}

Beberapa catatan:

• subject adalah subjek sebelum merge tag diisi.

• channel menunjukkan jalur kirim: api, smtp (SMTP relay), atau app (campaign/journey).

• events berisi riwayat dari yang terlama: delivered, deferred, bounce, complaint, open, click (dengan url), dan unsubscribe.

Daftar pesan#

curl -G https://api.kirim.id/v1/messages \
  -H "Authorization: Bearer $KIRIM_API_KEY" \
  --data-urlencode "status=bounced" \
  --data-urlencode "since=2026-09-01T00:00:00+07:00" \
  --data-urlencode "per_page=100"

{
  "data": [ { "...": "objek pesan seperti di atas, tanpa events" } ],
  "meta": {"current_page": 1, "last_page": 3, "per_page": 50, "total": 128}
}

Arti setiap status#

Laporan buka, klik, dan laporan spam tidak mengubah status — semuanya tercatat di events, opens, dan clicks.

Isi failed_reason untuk status failed#

• Domain pengirim tidak aktif. atau Workspace disuspend.

• Kontak sudah dihapus., Kontak sudah tidak berlangganan., Penerima ada di suppression list. — kondisi berubah setelah API menerima email.

• Saldo koin habis — top-up koin untuk lanjut mengirim. — saldo habis saat giliran kirim tiba.

• Penolakan permanen dari server pengiriman, atau penolakan sementara terus-menerus setelah percobaan ulang habis (maks. 3 hari).

• Tidak ada catatan pengiriman di server MTA — status akhir tidak diketahui. Koin dikembalikan.

• Lampiran kedaluwarsa, kalau email tertahan antrean lebih dari 4 hari.

Polling atau webhook?#

Mengecek status berulang-ulang (polling) menghabiskan kuota request. Untuk menerima status terkirim, bounce, dibuka, diklik, dan laporan spam secara langsung, pakai webhook. Simpan metadata (mis. order_id) saat mengirim supaya event mudah dicocokkan dengan data di sistemmu.

Langkah berikutnya#

• Webhook

• Kirim email lewat API

• Error & batas kecepatan