Idempotency Key: Kenapa Email Transaksional Butuh Exactly-Once, Bukan Best-Effort
Pernah terima invoice yang sama dua kali? Atau OTP masuk dobel beberapa detik berselang? Itu bukan bug kecil — itu tanda aplikasinya tidak punya idempotency. Dan untuk email transaksional, akibatnya bisa fatal: user panik didobel tagih, merchant bingung rekonsiliasi, support ticket menumpuk.
Akar Masalah: Retry Itu Wajib, Tapi Berbahaya
Jaringan tidak pernah sempurna. API kamu kirim permintaan, server lambat merespons, dan setelah 10 detik timeout klien memutuskan untuk coba lagi. Ternyata permintaan pertama sebenarnya sampai — email sudah terkirim. Retry kedua mengirim email yang sama sekali lagi.
Sekarang bayangkan itu email invoice Rp 5 juta. Atau email reset password. Atau notifikasi transaksi e-wallet.
Masalahnya bukan di retry — retry itu justru praktik bagus untuk keandalan. Masalahnya di tidak adanya cara bagi server membedakan "permintaan baru" dan "retry dari permintaan yang sama".
Apa Itu Idempotency Key
Idempotency key adalah identifier unik yang kamu kirimkan bersama setiap permintaan. Server menyimpan key itu, dan jika key yang sama datang lagi, server tidak mengirim ulang email — ia mengembalikan hasil dari permintaan pertama.
Sederhananya: satu key = satu email, tidak peduli berapa kali retry terjadi.
POST /v1/emails
Idempotency-Key: invoice-88321-20260823
Content-Type: application/json
{
"from": "[email protected]",
"to": "[email protected]",
"subject": "Invoice #88321",
"text": "Total: Rp 5.000.000"
}
Kalau permintaan ini timeout dan kamu kirim ulang dengan Idempotency-Key yang sama, MailAnvil mengenalinya sebagai retry. Email tetap terkirim sekali. Merchant menerima satu invoice, bukan dua.
Tiga Use Case yang Paling Rentan Duplikasi
Invoice dan dokumen finansial. Email ganda = tagihan ganda di mata merchant. Satu kesalahan retry bisa memicu dispute, refund, dan hilangnya kepercayaan. Idempotency key di sini bukan best practice — ini proteksi reputasi.
OTP dan kode verifikasi. Kode masuk dua kali bikin user bingung mana yang valid. Kalau keduanya punya masa berlaku berbeda, user bisa memasukkan kode yang sudah kedaluwarsa dan terkunci dari akunnya sendiri.
Password reset dan magic link. Link ganda yang muncul berbarengan memicu kecurigaan — user mengira akunnya diserang. Padahal cuma retry polos dari server kamu.
Ketiganya punya pola sama: biaya duplikasi jauh lebih mahal daripada biaya implementasi idempotency.
Cara Memilih Key yang Benar
Jangan pakai timestamp atau UUID acak. Kalau key-nya acak, setiap retry menghasilkan key baru — dan server tidak bisa mendeteksi duplikasi. Retry harus mengirim key yang sama dengan permintaan aslinya.
Pakai identifier bisnis yang stabil. Yang terbaik adalah sesuatu yang sudah unik di sistemmu: orderId, invoiceId, bookingId, userId + aksi. Key ini sama persis setiap kali kamu me-retry permintaan yang sama.
// Retry dengan key yang sama
const idempotencyKey = `invoice-${invoiceId}`;
await fetch('https://api.mailanvil.com/v1/emails', {
method: 'POST',
headers: {
'Idempotency-Key': idempotencyKey,
'Authorization': 'Bearer MA_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
});
invoiceId tidak berubah saat retry, jadi key-nya identik, dan server menolak pengiriman ganda.
Ganti key ketika isi email berubah. Kalau kamu mengubah payload (misalnya total invoice berubah setelah revisi), itu memang email baru — gunakan key baru. Satu key merepresentasikan satu versi konten, bukan satu proses bisnis selamanya.
Beyond Retry: Konsistensi Lintas Sistem
Idempotency bukan cuma soal retry. Saat kamu mengirim email lalu mencatat statusnya ke database, urutan "kirim dulu" atau "simpan dulu" menentukan konsistensi. Kalau kirim berhasil tapi pencatatan gagal, retry akan mengirim ulang — kecuali ada idempotency key.
Dengan key, kamu bisa mengirim ulang dengan aman tanpa takut dobel, sehingga logika retry jadi jauh lebih sederhana dan tidak perlu state machine yang rumit.
Intinya
Retry tanpa idempotency = duplikasi menunggu untuk terjadi. Retry dengan idempotency = keandalan tanpa risiko.
Untuk email transaksional — invoice, OTP, reset password — idempotency key bukan fitur mewah, tapi syarat dasar. Pilih email API yang mendukungnya dari awal, bukan yang memintamu menambal sendiri.
MailAnvil mendukung Idempotency-Key di setiap endpoint pengiriman, dengan harga rupiah mulai Rp 149 ribu per bulan untuk 10.000 email, pembayaran QRIS/GoPay, dan dokumentasi Bahasa Indonesia.
Coba gratis di mailanvil.com — 500 email per bulan, tanpa kartu kredit.