Apa itu Email API?

Email API adalah REST API untuk email aplikasi — notifikasi, invoice, verifikasi, reset password. Aplikasi Anda mengirim satu request JSON per batch ke /email-api/messages, dan RuangMail yang mengurus validasi, penghitungan kredit, antrean kuota, pengiriman, sampai pencatatan open dan click.

Ini bukan relay SMTP. Kalau aplikasi Anda sudah punya SMTP client dan tidak mau menulis kode HTTP, pakai jalur SMTP — hasilnya sama, titik masuknya berbeda. Buka panduan SMTP by Azure

curl -X POST https://api.ruangmail.com/api/v1/email-api/messages \
  -H "Authorization: Bearer rmk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-202610-000482" \
  -d '{
    "from": "[email protected]",
    "from_name": "Brand Anda",
    "reply_to": "[email protected]",
    "to": [{"email": "[email protected]", "name": "Customer"}],
    "subject": "Invoice INV-202610-000482",
    "html": "<p>Terima kasih, pembayaran Anda sudah kami terima.</p>",
    "metadata": {"invoice_id": "INV-202610-000482"}
  }'

{
  "data": {
    "batch_id": "3f9a1c72-1d84-4b60-9a11-7c0e5b2f8d31",
    "status": "sent",
    "message_ids": ["8b2d4e01-5c77-4a19-b3e2-90af6d1c4471"],
    "final_size_bytes": 1420,
    "credit_per_recipient": 1,
    "total_credit_cost": 1
  },
  "meta": { "request_id": "req_9c1f4a" }
}

Untuk volume besar, isi array to dengan sampai 50 penerima unik dalam satu request. Batch 50 penerima berukuran normal memakai 50 kredit dan tetap satu panggilan.

{
  "from": "[email protected]",
  "to": [
    { "email": "[email protected]" },
    { "email": "[email protected]" },
    { "email": "[email protected]" }
  ],
  "subject": "Pengumuman layanan",
  "html": "<p>Ada pemeliharaan terjadwal malam ini.</p>"
}

unit per menit

18.000

penerima per 24 jam berjalan

50.000

penerima per request

50

Reservasi kuota memakai bucket per menit di dalam transaksi database dengan advisory lock, sehingga beberapa instance backend dan worker tidak bisa melewati batas secara bersamaan. Dashboard Email API menampilkan pemakaian menit dan 24 jam berjalan terhadap batas ini.

Kuota penuh bukan kegagalan. Request dijawab 202 dan masuk antrean durable; worker mengirim ulang otomatis dan kredit tidak ditahan selama masih mengantre. Untuk kebutuhan kapasitas di atas anggaran ini, hubungi support.

Membaca hasilnya

Riwayat pesan mengembalikan open_count, click_count, opened_at, dan clicked_at. Counter menghitung event yang sudah dideduplikasi, dan waktu menunjukkan kejadian pertama.

{
  "id": "8b2d4e01-5c77-4a19-b3e2-90af6d1c4471",
  "status": "delivered",
  "open_count": 3,
  "click_count": 1,
  "opened_at": "2026-10-03T02:14:07Z",
  "clicked_at": "2026-10-03T02:14:31Z"
}

Kredit per penerima

Pesan di atas 2.008.192 byte ditolak sebelum kredit dipotong. Karena batas ukuran sudah 2 MB, tier yang lebih tinggi tidak akan pernah terpakai di jalur ini.

Batas teknis per request

Alamat yang sedang di-suppress dilewati sebelum pengiriman dipanggil, jadi tidak memakan kredit. Hard bounce atau keluhan spam menambahkan alamat ke daftar suppression, dan setiap event bounce yang unik mengenakan penalti 30 kredit satu kali. Kegagalan sementara tidak langsung menjadi suppression permanen.

Idempotency-Key wajib, bukan opsional

Tanpa key ini request ditolak. Key yang sama dengan payload yang sama mengembalikan hasil lama dengan reused, sedangkan payload berbeda dengan key yang sama menjawab 409. Jangan pakai ulang key untuk isi yang berubah.

Tracking hilang begitu penerima lebih dari satu

Pixel dan redirect hanya dipasang pada email HTML dengan satu penerima. Kalau angka open penting, kirim satu request per penerima — penerima tetap bisa diisi sampai 50 untuk email yang tidak butuh tracking.

Kuota penuh bukan error

Request dijawab 202 dan masuk antrean durable. Kredit tidak ditahan selama mengantre, dan worker mengirim ulang sendiri. Jangan retry dari sisi Anda hanya karena melihat 202.

Lampiran dihitung setelah base64

Batas 2.008.192 byte berlaku untuk ukuran akhir MIME, termasuk encoding base64, header, dan boundary. Lampiran 1,6 MB mentah bisa melewati batas setelah di-encode, dan pesan ditolak sebelum kredit dipotong.

Bounce tidak cuma gagal

Alamat yang bounce masuk suppression dan pengiriman berikutnya ke alamat itu dilewati sebelum kredit didebit. Setiap event bounce unik juga memotong 30 kredit sekali, dan deduplikasi mencegah penalti ganda.

Reply-To kosong otomatis jadi From

Kalau Anda tidak mengisi reply_to, balasan pelanggan masuk ke alamat pengirim. Isi eksplisit kalau balasan harus diarahkan ke tempat lain.

Lanjut baca

Halaman yang biasanya dibuka setelah yang ini.