Mulai cepat: kirim email pertama lewat API

REST API kirim.id dibuat untuk email transaksional dari aplikasimu: kode verifikasi, reset password, invoice, sampai notifikasi pesanan. Panduan ini mengajak kamu dari nol sampai email pertama terkirim — biasanya cukup beberapa menit kalau domain pengirimmu sudah aktif.

Sebelum mulai#

• Akun kirim.id dengan modul Email Marketing aktif. Tanpa modul ini, semua endpoint menjawab 403.

• Domain pengirim yang sudah berstatus active. Email hanya bisa dikirim dari domain yang sudah terverifikasi — lihat Verifikasi domain pengirim.

• Server (backend) untuk memanggil API. API ini khusus server-ke-server.

Tiga langkah kirim email pertama#

1. Aktifkan domain pengirim

   Buka Settings → Domains di dashboard, tambahkan domain bisnismu, lalu pasang baris DNS yang diberikan sampai statusnya active.

2. Buat API key

   Buka Settings → API Keys, buat key baru dengan scope Kirim Email (send_email). Simpan key di server, misalnya sebagai environment variable KIRIM_API_KEY.

3. Ambil ID domain, lalu kirim

   Panggil GET /v1/domains untuk mendapatkan id domain yang aktif, lalu kirim email lewat POST /v1/messages dengan sending_domain_id tersebut.

1. Cari ID domain pengirim#

curl https://api.kirim.id/v1/domains \
  -H "Authorization: Bearer $KIRIM_API_KEY"

# [{"id":1,"domain":"tokomu.com","status":"active"}]

2. Kirim email#

curl -X POST https://api.kirim.id/v1/messages \
  -H "Authorization: Bearer $KIRIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "subject": "Pesanan {{nama|Kakak}} sudah kami terima",
    "html": "<p>Halo {{nama_depan|Kak}}, pesanan #1001 sedang diproses.</p>",
    "sending_domain_id": 1
  }'

Kalau berhasil, kamu menerima jawaban 201:

{"message_id":"9b1c7e2a-5d0f-4b8e-9a51-3f0c2d6e7a10","status":"queued"}

Status queued berarti email sudah diterima dan menunggu giliran kirim. Koin baru dipotong (1 koin per email) saat email benar-benar diserahkan ke server pengiriman, bukan saat API menerimanya. Simpan message_id — kamu butuh untuk mengecek status dan mencocokkan event webhook.

3. Cek statusnya#

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

Yang sering membuat request pertama gagal#

• 401 — header Authorization tidak ada, key salah ketik, atau key sudah dicabut.

• 403 — key tidak punya scope send_email, atau modul Email belum aktif.

• 422 "Domain pengirim belum aktif/terverifikasi." — sending_domain_id salah atau domain belum active.

• 422 "Saldo koin habis" — isi ulang koin dulu. Akun baru mendapat 1.000 koin gratis.

Langkah berikutnya#

• Autentikasi & API key — format key dan pilihan scope.

• Kirim email lewat API — semua field, lampiran, personalisasi, dan anti kirim dobel.

• Webhook — terima laporan pengiriman secara real-time.

• Error & batas kecepatan

• Cara kerja koin