Kirim email lewat API (POST /v1/messages)

Endpoint POST /v1/messages adalah inti API kirim.id: satu request mengirim satu email ke satu penerima. Endpoint ini cocok untuk email transaksional seperti kode verifikasi, reset password, invoice, dan notifikasi pesanan. Di artikel ini kamu akan menemukan semua field yang didukung, aturan lampiran, cara mencegah email terkirim dobel, dan apa saja yang otomatis ditambahkan kirim.id ke setiap email.

Field request#

CC/BCC dan header kustom belum didukung; field yang tidak dikenal diabaikan.

Contoh lengkap#

curl -X POST https://api.kirim.id/v1/messages \
  -H "Authorization: Bearer $KIRIM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001-invoice" \
  -d '{
    "to": "[email protected]",
    "subject": "Invoice pesanan #1001",
    "html": "<p>Halo {{nama_depan|Kak}}, invoice terlampir.</p>",
    "text": "Halo {{nama_depan|Kak}}, invoice terlampir.",
    "sending_domain_id": 1,
    "from_email": "[email protected]",
    "from_name": "Toko Rina",
    "reply_to": "[email protected]",
    "metadata": {"order_id": "1001", "source": "woocommerce"},
    "attachments": [
      {"filename": "invoice-1001.pdf", "content": "JVBERi0xLjQK...", "content_type": "application/pdf"}
    ]
  }'

Urutan pemeriksaan#

Sebelum email masuk antrean, kirim.id memeriksa request secara berurutan:

1. Alamat to rusak (bukan format email / lebih dari 255 karakter) → penalti 4 koin, lalu 422.

2. Validasi field, metadata, dan lampiran → 422.

3. Domain harus milikmu dan aktif; from_email harus di domain itu → 422.

4. Saldo koin minimal 1 → kalau tidak, 422 Saldo koin habis.

5. Penerima di suppression list → penalti + 422.

6. Penerima dijadikan kontak (dibuat otomatis bila belum ada). Kalau kontak sudah unsubscribe/bounce/melapor spam → penalti + 422.

7. Email masuk antrean → 201.

Lampiran#

• Maksimal 10 lampiran dan total 10 MB (ukuran asli, sebelum base64) per email. Batas body request 20 MB.

• Ekstensi berisiko malware ditolak, mis. .exe, .bat, .js, .vbs, .msi, .iso, .apk, .scr, .ps1. Kirim lewat link unduhan.

• File hanya disimpan sampai email diserahkan ke server pengiriman. Kalau email tertahan antrean lebih dari 4 hari, pesan berstatus failed karena lampiran kedaluwarsa.

• Biaya tetap 1 koin per email berapa pun lampirannya — tapi email besar lebih lambat dan lebih sering masuk spam.

Anti kirim dobel (Idempotency-Key)#

Jaringan bisa putus setelah kirim.id menerima email tapi sebelum jawabannya sampai ke server-mu. Kalau request diulang tanpa pengaman, penerima bisa mendapat dua email. Tambahkan header Idempotency-Key:

• 8–100 karakter, unik per email yang ingin dikirim (mis. ID pesanan + jenis email: order-1001-invoice). Berlaku per akun, tanpa batas waktu.

• Request pertama → 201. Request berikutnya dengan key yang sama → 200 berisi message_id & status pesan pertama, tanpa email baru dan tanpa potong koin. Isi body request ulang tidak diperiksa.

• Kalau request pertama ditolak (4xx), tidak ada yang tersimpan — key yang sama boleh dipakai lagi setelah diperbaiki.

Personalisasi (merge tag)#

Tulis {{nama_tag}} di subject, html, atau text. Tambahkan cadangan dengan {{nama_tag|Cadangan}} untuk dipakai kalau datanya kosong. Nama tag tidak peka huruf besar/kecil, tag tak dikenal dibiarkan apa adanya, dan nilai otomatis di-escape untuk HTML.

Tag {{link_browser}}, {{versi_web}}, dan {{preheader}} hanya untuk campaign — di email API isinya kosong.

Pelacakan, unsubscribe & header#

• Pelacakan klik — setiap link href="http(s)://…" (tanda kutip ganda) diganti link pelacak yang langsung meneruskan ke tujuan asli. Link mailto:, tel:, atau tanpa tanda kutip ganda tidak dilacak.

• Pelacakan buka — gambar 1×1 piksel ditambahkan di akhir email. Sebagian aplikasi (mis. Apple Mail) memuat gambar otomatis, jadi angka "dibuka" bisa sedikit lebih tinggi.

• Unsubscribe — kalau isi email belum memuat link unsubscribe, kirim.id menambahkan footer berisi nama & alamat bisnis plus link "Berhenti berlangganan". Email juga membawa header List-Unsubscribe dan List-Unsubscribe-Post: List-Unsubscribe=One-Click (syarat Gmail & Yahoo).

• Header lain — Message-ID, X-Campaign-id: api, X-Subscriber-id, X-Message-id. Return-Path memakai subdomain bounce domainmu dan email ditandatangani DKIM domainmu.

Pelacakan buka/klik dan footer unsubscribe tidak bisa dimatikan.

Langkah berikutnya#

• Status & daftar pesan

• Webhook

• Error & batas kecepatan

• SPF, DKIM, dan DMARC