API kontak, audience, campaign, journey, dan konversi

Ringkasan endpoint untuk mengelola kontak & audience, memicu campaign dan journey, serta mencatat penjualan dari email lewat API kirim.id.

Developer Diperbarui 4 Oktober 2026 4 menit bacaKB-13

Di halaman ini

Kontak
Kontak teraktif
Audience
Campaign
Journey
Konversi (revenue)
Langkah berikutnya

Selain mengirim email transaksional, API kirim.id bisa menyinkronkan pelanggan dari websitemu ke kontak dan audience, menjalankan campaign yang sudah kamu siapkan di dashboard, memasukkan orang ke journey otomatis, dan mencatat penjualan supaya kamu tahu berapa rupiah yang datang dari email. Artikel ini merangkum endpoint-endpoint tersebut.

Kontak#

Semua endpoint kontak butuh scope manage_contacts. Status kontak: subscribed, unsubscribed, bounced, complained.

GET/v1/contacts

Daftar kontak, 50 per halaman, urut ID. Filter opsional: email (cari satu kontak) dan status.

POST/v1/contacts

Membuat kontak. Field: email (wajib, maks. 255), name (opsional, maks. 255), consent (wajib, harus true).

Selalu menjawab 201. Kalau email sudah ada, kontak lama dikembalikan tanpa diubah — nama tidak diperbarui dan status tidak dikembalikan ke subscribed. Kontak baru tidak otomatis masuk audience mana pun.

cURL

curl -X POST https://api.kirim.id/v1/contacts \
  -H "Authorization: Bearer $KIRIM_API_KEY" -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","name":"Rina","consent":true}'

GET/v1/contacts/{id}

Objek kontak ditambah audiences (daftar {id, name} audience yang diikutinya).

PATCH/v1/contacts/{id}

Mengubah name (wajib ada, boleh null). Status langganan tidak bisa dikembalikan ke subscribed lewat API — itu harus persetujuan penerima sendiri lewat form subscribe.

POST/v1/contacts/{id}/unsubscribe

Menghentikan langganan kontak, misalnya saat pengguna mematikan "terima email promo" di akun websitemu.

DELETE/v1/contacts/{id}

Menghapus kontak permanen; riwayat pesannya dianonimkan. Jawaban: {"deleted":true}.

Menghapus kontak tidak memblokirnya. Kontak yang dihapus lalu dikirimi lagi lewat API akan dibuat ulang sebagai subscribed. Untuk memblokir alamat, pakai Daftar Filter di dashboard.

Kontak teraktif#

GET/v1/contacts/engagement

Kontak yang paling rajin membuka atau mengklik emailmu, dihitung per email unik.

Parameter	Bawaan	Keterangan
`by`	`opens`	`opens` = paling rajin buka, `clicks` = paling rajin klik
`days`	90	Periode ke belakang (1–3650). `0` = semua waktu
`audience_id`	—	Hanya kontak di audience ini
`per_page` · `page`	50 · 1	`per_page` maks. 200

Audience#

GET/v1/audiences

Daftar audience beserta opt_in_mode (single/double) dan contacts_count.

POST/v1/audiences

Membuat audience. Field: name (wajib, maks. 255), description (opsional, maks. 1000). Audience baru selalu single opt-in; mode opt-in hanya bisa diubah dari dashboard.

GET/v1/audiences/{id}

Satu audience, ditambah contacts_count dan confirmed_count.

GET/v1/audiences/{id}/contacts

Anggota audience, urut ID. Parameter: status, per_page (maks. 200), page.

POST/v1/audiences/{id}/contacts

Memasukkan orang ke audience — untuk form subscribe di websitemu, centang "mau terima promo" saat checkout, atau sinkron pelanggan.

Field	Wajib	Aturan
`email`	ya	Email valid, maks. 255
`name`	tidak	Maks. 255 — hanya mengisi nama kalau kontak belum punya nama
`consent`	ya	Harus `true`
`source`	tidak	`api` (bawaan), `form`, `checkout`, `import`. `form` juga memicu journey "Isi form subscribe".

Single opt-in: langsung confirmed dan memicu journey "Masuk audience".
Double opt-in: pending_confirmation — kirim.id mengirim email konfirmasi; setelah diklik, kontak aktif dan journey terpicu.
Sudah menjadi anggota → 200 dengan created: false; journey tidak dipicu ulang.
Orang yang sudah berhenti langganan hanya bisa bergabung lagi lewat form subscribe publik (422, tanpa penalti).

DELETE/v1/audiences/{id}/contacts/{contact_id}

Mengeluarkan kontak dari audience; kontaknya tetap ada. Jawaban: {"removed":true}, atau false kalau memang bukan anggota.

Campaign#

Butuh scope send_email.

GET/v1/campaigns

Daftar campaign, terbaru dulu, tanpa paginasi. Status: draft, scheduled, live, paused, completed.

POST/v1/campaigns/{id}/send

Mengirim campaign berstatus draft yang sudah kamu siapkan di dashboard (isi, audience, pengirim). Jawaban: {"id":28,"status":"live"}, atau completed kalau tidak ada penerima yang memenuhi syarat.

Penerima adalah anggota audience yang subscribed, tidak di suppression list, dan sudah konfirmasi (untuk double opt-in). Penolakan 422 terjadi bila alamat bisnis belum diisi, domain pengirim belum aktif, konten belum diisi, saldo koin tidak cukup untuk seluruh penerima, atau campaign bukan draft.

Journey#

GET/v1/journeys

Daftar journey dengan status (draft, active, paused) dan trigger_type (form_subscribe, audience_join, api).

POST/v1/journeys/{id}/enroll

Memasukkan kontak ke journey yang pemicunya API. Field: email (wajib), name (opsional, hanya untuk kontak baru), consent (wajib true).

cURL

curl -X POST https://api.kirim.id/v1/journeys/5/enroll \
  -H "Authorization: Bearer $KIRIM_API_KEY" -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","name":"Budi","consent":true}'

# 201 {"journey_id":5,"email":"[email protected]","enrolled":true,"message":"Kontak masuk journey."}

Satu kontak hanya bisa masuk satu journey sekali (request ulang menjawab 200 dengan enrolled: false). Langkah journey diproses tiap menit.

Konversi (revenue)#

POST/v1/conversions

Mencatat penjualan dari sistemmu. Penjualan dihubungkan ke klik email terakhir dalam 7 hari sebelum waktu penjualan. Scope: send_email.

Field	Wajib	Aturan
`amount`	ya	Rupiah bulat, 0 s.d. 10.000.000.000
`email`	salah satu	Email pembeli (dicocokkan ke kontak)
`message_id`	salah satu	UUID pesan yang diklik — paling akurat. Didapat dari parameter `kirim_mid` di URL tujuan klik. Kalau diisi, `email` diabaikan.
`order_id`	tidak	Maks. 191. ID yang sama dianggap duplikat, jadi aman diulang.
`occurred_at`	tidak	Waktu penjualan, tidak boleh di masa depan. Sertakan zona waktu; tanpa zona dianggap UTC.

Parameter kirim_mid hanya ditambahkan ke link kalau pelacakan konversi aktif di akunmu. Konversi yang tidak bisa dihubungkan ke klik email tidak disimpan.

Langkah berikutnya#

Autentikasi & scope
Webhook
WooCommerce — opt-in checkout dan laporan omzet tanpa coding.

Apakah artikel ini membantu?

Kontak#

Kontak teraktif#

Audience#

Campaign#

Journey#

Konversi (revenue)#

Langkah berikutnya#

Artikel terkait