Cara Kirim Email via API Mailketing — Dokumentasi Lengkap (POST /send)
Di halaman ini
Panduan ini menjelaskan cara mengirim email transaksional (invoice, OTP, notifikasi pesanan) dari aplikasi Anda lewat API v2 Mailketing dengan satu request POST /send. Dokumentasi interaktifnya ada di https://api.mailketing.co.id/docs/.
Untuk developer, mengirim lewat API adalah pilihan yang lebih baik daripada akses SMTP langsung. Lewat API, Mailketing otomatis menyaring alamat penerima yang bounce, alamat yang salah (bad address), atau setup yang tidak valid, sehingga pengiriman lebih bersih dan reputasi domain Anda lebih terjaga.
Yang Perlu Disiapkan
- Akun Mailketing dengan saldo kredit. Satu email terkirim memakai 1 kredit. Akun baru mendapat 200 email credit gratis saat mendaftar.
- Domain pengirim yang sudah diverifikasi di Pengaturan → Sender & Domain. Panduannya: Whitelabel Sender (Cloudflare) atau Whitelabel Sender (cPanel).
- API token dari menu Pengaturan → API Email.
Langkah-langkah Kirim Email via API
Langkah 1: Ambil API token
- Masuk ke dashboard di be.mailketing.co.id/login.
- Buka menu Pengaturan → API Email.
- Di kotak Token dan endpoint (v2), klik tombol Salin di samping kolom API token.
Penting: Tombol Buat ulang token membuat token pengganti. Token lama langsung tidak berlaku, jadi semua aplikasi yang memakai token lama harus diperbarui. Simpan token di server (misalnya variabel lingkungan), jangan ditaruh di kode JavaScript yang berjalan di browser pengunjung.
Langkah 2: Pastikan email pengirim sudah aktif
Buka Pengaturan → Sender & Domain dan cek domain dari alamat yang akan dipakai di from_email. Jika domain belum terdaftar atau belum aktif, API menolak dengan HTTP 403.
Langkah 3: Kirim request ke endpoint
| Bagian | Nilai |
|---|---|
| Method | POST |
| URL | https://api.mailketing.co.id/api/v2/send |
| Header | Content-Type: application/json dan Authorization: Bearer TOKEN_ANDA |
| Body | JSON berisi from_name, from_email, subject, recipient, content |
Token juga bisa dikirim dengan cara lain. Pilih salah satu saja:
| Cara mengirim token | Contoh |
|---|---|
Header Authorization (disarankan) | Authorization: Bearer TOKEN_ANDA |
Header X-Api-Token | X-Api-Token: TOKEN_ANDA |
| Query string | ?api_token=TOKEN_ANDA |
| Body JSON | {"api_token": "TOKEN_ANDA"} |
Contoh cURL (minimal)
curl -X POST "https://api.mailketing.co.id/api/v2/send" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN_ANDA" \
-d '{
"from_name": "Toko Budi",
"from_email": "[email protected]",
"subject": "Pesanan Anda sudah kami terima",
"recipient": "[email protected]",
"content": "<html><body><h1>Terima kasih</h1><p>Pesanan Anda sedang diproses.</p></body></html>"
}'Contoh cURL dengan lampiran
curl -X POST "https://api.mailketing.co.id/api/v2/send" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN_ANDA" \
-d '{
"from_name": "Toko Budi",
"from_email": "[email protected]",
"subject": "Invoice #1001",
"recipient": "[email protected]",
"content": "<html><body><p>Invoice terlampir.</p></body></html>",
"attach1": "https://domainanda.com/files/invoice-1001.pdf",
"attach2": "https://domainanda.com/files/syarat.pdf",
"attach3": "https://domainanda.com/files/panduan.pdf"
}'Contoh PHP
<?php
$apiToken = 'TOKEN_ANDA'; // dari menu Pengaturan → API Email
$data = [
'from_name' => 'Toko Budi',
'from_email' => '[email protected]', // domain harus sudah diverifikasi
'subject' => 'Pesanan Anda sudah kami terima',
'recipient' => '[email protected]',
'content' => '<html><body><h1>Terima kasih</h1><p>Pesanan Anda sedang diproses.</p></body></html>',
// 'attach1' => 'https://domainanda.com/files/invoice.pdf', // opsional
];
$ch = curl_init('https://api.mailketing.co.id/api/v2/send');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($data),
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'Authorization: Bearer ' . $apiToken,
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60, // beri waktu lebih bila ada lampiran
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$result = json_decode($response, true);
if (!empty($result['success'])) {
// simpan message_id untuk dicocokkan dengan data webhook (open, bounce)
echo 'Terkirim ke antrean, message_id: ' . $result['data']['message_id'];
} else {
echo 'Gagal (' . $httpCode . '): ' . ($result['message'] ?? $response);
}Contoh JavaScript (Node.js)
// Node.js 18 ke atas (fetch sudah bawaan). Jalankan di server, bukan di browser.
const apiToken = process.env.MAILKETING_TOKEN; // isi dengan token Anda
async function kirimEmail() {
const res = await fetch('https://api.mailketing.co.id/api/v2/send', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${apiToken}`,
},
body: JSON.stringify({
from_name: 'Toko Budi',
from_email: '[email protected]',
subject: 'Pesanan Anda sudah kami terima',
recipient: '[email protected]',
content: '<html><body><h1>Terima kasih</h1><p>Pesanan Anda sedang diproses.</p></body></html>',
}),
});
const result = await res.json();
if (result.success) {
console.log('message_id:', result.data.message_id);
} else {
console.error('Gagal', res.status, result.message, result.errors || '');
}
}
kirimEmail();Contoh Python
import os
import requests
api_token = os.environ.get("MAILKETING_TOKEN", "TOKEN_ANDA")
resp = requests.post(
"https://api.mailketing.co.id/api/v2/send",
headers={"Authorization": f"Bearer {api_token}"},
json={
"from_name": "Toko Budi",
"from_email": "[email protected]",
"subject": "Pesanan Anda sudah kami terima",
"recipient": "[email protected]",
"content": "<html><body><h1>Terima kasih</h1><p>Pesanan Anda sedang diproses.</p></body></html>",
},
timeout=60,
)
result = resp.json()
if result.get("success"):
print("message_id:", result["data"]["message_id"])
else:
print("Gagal", resp.status_code, result.get("message"), result.get("errors"))Daftar Field
| Field | Wajib | Tipe | Keterangan |
|---|---|---|---|
from_name | Ya | teks (maks. 255) | Nama pengirim yang tampil di kotak masuk. |
from_email | Ya | email (maks. 255) | Email pengirim. Domainnya harus sudah ditambahkan dan aktif di menu Pengaturan → Sender & Domain. |
subject | Ya | teks (maks. 998) | Judul email. |
recipient | Ya | email (maks. 255) | Alamat email penerima. Satu request untuk satu penerima. |
content | Ya | teks | Isi email. HTML (mengandung tag <html>) tidak dibatasi ukurannya; teks biasa maksimal 300 KB. |
attach1, attach2, attach3 | Tidak | URL | Link langsung ke file lampiran (http/https publik). Server Mailketing mengunduh file lalu melampirkannya. |
Tentang message_id: message_id tidak bisa diisi sendiri. Mailketing membuatnya otomatis untuk setiap email (format <api.{acak}@domain-pengirim>) dan mengembalikannya di respons sebagai data.message_id. Simpan nilai ini untuk mencocokkan event webhook (open, bounce).
Catatan: Konten dianggap HTML hanya jika mengandung tag
<html>. Tanpa tag itu, konten diperlakukan sebagai teks biasa: tag seperti<h1>akan tampil apa adanya dan baris baru diubah menjadi jeda baris. Jadi bungkus email HTML dengan<html><body>…</body></html>.
Aturan lampiran
- Isi dengan link langsung ke file yang bisa diakses publik lewat http atau https, bukan path file di komputer.
- Ukuran maksimal 25 MB per file. Agar email tidak berat, pakai file sekecil mungkin.
- Link ke localhost, IP privat, atau skema selain http/https ditolak dengan HTTP 400 (
Invalid attach1: attachment must be a public http(s) URL). - Jika file gagal diunduh (misalnya link 404 atau server file lambat), lampiran itu dilewati dan email tetap dikirim tanpa lampiran tersebut.
- Pengunduhan lampiran butuh waktu, jadi atur timeout di aplikasi Anda minimal 30–60 detik.
Contoh Respons
Semua respons API v2 berbentuk JSON dengan pola yang sama: success (true/false), data (isi hasil, null bila gagal), message (pesan singkat), dan errors (hanya muncul bila ada field yang tidak valid).
Berhasil masuk antrean kirim (HTTP 200)
{
"success": true,
"data": {
"message_id": "<[email protected]>"
},
"message": "Email queued successfully"
}Simpan message_id dari respons. Nilai yang sama dikirim kembali oleh webhook pada event open dan bounce, sehingga Anda bisa mencocokkan status setiap email.
Contoh domain pengirim belum diverifikasi (HTTP 403)
{
"success": false,
"data": null,
"message": "Unknown sender domain. Please add your sender email in Add Domain menu."
}Contoh error validasi (HTTP 422)
{
"success": false,
"data": null,
"message": "Validation failed",
"errors": {
"recipient": "Recipient must be a valid email",
"subject": "Subject is required"
}
}| HTTP | Pesan | Penyebab |
|---|---|---|
| 400 | Invalid attach1: … | URL lampiran tidak aman/bukan URL publik, atau file lebih dari 25 MB. |
| 401 | Missing API token / Invalid API token | Token tidak dikirim atau salah. |
| 402 | Insufficient credits / No credits. Please top up. | Saldo kredit habis. Isi kredit dulu. |
| 403 | Unknown sender domain… | Domain from_email belum ditambahkan atau belum aktif di Pengaturan → Sender & Domain. |
| 422 | Validation failed | Ada field kosong atau salah format. Detailnya di errors. |
| 429 | Rate limit exceeded | Terlalu banyak request gagal dalam satu menit. |
Request yang berhasil tidak dibatasi. Yang dibatasi hanya request yang gagal: maksimal 30 kali gagal per menit per alamat IP. Lewat dari itu, API menjawab HTTP 429 sampai jedanya habis (lihat header Retry-After).
Cara Memastikan Berhasil
- Kirim email uji ke alamat Anda sendiri.
- Pastikan respons berisi
"success": truedan adamessage_id. - Cek kotak masuk (dan folder spam/promosi) di alamat tujuan.
- Jika memakai webhook, pastikan event open/bounce yang masuk membawa
message_idyang sama.
Pertanyaan yang Sering Diajukan
Respons sukses, tapi email belum masuk. Kenapa?
Email queued successfully berarti email sudah masuk antrean kirim. Tunggu sebentar, lalu cek folder spam. Jika penerima ternyata bounce, Anda bisa menerima kabarnya lewat webhook event Bounce.
Bisakah mengirim ke banyak penerima sekaligus?
Satu request POST /send untuk satu alamat di recipient. Untuk banyak penerima, kirim satu request per alamat. Untuk broadcast ke list, gunakan Campaign di dashboard.
Muncul error 403 padahal domain sudah ditambahkan.
Pastikan ejaan domain di from_email sama persis dengan yang terdaftar dan statusnya sudah aktif di Pengaturan → Sender & Domain.
Apakah aman memanggil API dari JavaScript di browser?
Tidak disarankan, karena token akan terlihat oleh pengunjung. Panggil API dari server (PHP, Node.js, Python, dan sebagainya).
Masih Memakai API v1?
Catatan: API v1 masih berfungsi untuk integrasi lama. Untuk integrasi baru, gunakan API v2 seperti di atas.
| Bagian | Nilai (v1) |
|---|---|
| URL | https://api.mailketing.co.id/api/v1/send |
| Method | POST |
| Format | Form (application/x-www-form-urlencoded) atau JSON. Token dikirim sebagai parameter api_token. |
Parameter v1
- [api_token]: didapatkan di menu Pengaturan → API Email.
- [from_name]: nama pengirim email.
- [from_email]: email pengirim.
- [recipient]: alamat email tujuan/penerima.
- [subject]: subject/judul email.
- [content]: isi email (teks atau HTML).
- [attach1], [attach2], [attach3]: link langsung ke file lampiran (opsional). Dokumen lama menyebut maksimal 2 MB; batas server saat ini 25 MB per file.
Contoh PHP (v1)
<?php
$api_token='isi_api_token'; //silahkan copy dari api token mailketing
$from_name='dari contoh'; //nama pengirim
$from_email='[email protected]'; //email pengirim
$subject='test email'; //judul email
$content='Ini Hanya Test Email'; //isi email format text / html
$recipient='[email protected]'; //penerima email
$params = [
'from_name' => $from_name,
'from_email' => $from_email,
'recipient' => $recipient,
'subject' => $subject,
'content' => $content,
'attach1' => 'direct url file httxxx/xxx/xx.pdf',
'attach2' => 'direct url file httxxx/xxx/xx.pdf',
'attach3' => 'direct url file httxxx/xxx/xx.pdf',
'api_token' => $api_token
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,"https://api.mailketing.co.id/api/v1/send");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$output = curl_exec ($ch); print_r($output);
curl_close ($ch);
?>Respons v1
{"status":"success","response":"Mail Sent"}| Status | Response | Deskripsi |
|---|---|---|
| success | Mail Sent | Email diterima untuk dikirim ke tujuan. |
| failed | User Not Found or Wrong API Token | User Mailketing tidak ditemukan atau API token salah (juga muncul jika saldo kredit 0). |
| failed | Access Denied, Invalid Token | Token tidak diisi. |
| failed | Unknown Sender, Please Add your Sender Email at Add Domain Menu | Email pengirim belum ditambahkan di menu Pengaturan → Sender & Domain. Tambahkan dulu. |
| failed | Empty From Name | From Name kosong. |
| failed | No Credits, Please Top Up | Kredit habis. Silakan isi kredit dulu. |
| failed | Empty Recipient, Please Add recipient address | Email penerima tidak diisi. |
| failed | Blacklisted | Email penerima masuk blacklist karena tidak valid, palsu (fake), sekali pakai (disposable), atau email spam. |
| failed | Empty Subject, Please Add Subject Email | Subject kosong. |
| failed | Empty Content, Please Add Email Content | Isi email kosong. |
| failed | Oversize Content, Reduce Content below 300kb | Konten teks biasa lebih dari 300 KB. |
Koleksi Postman lama (API v1): Run in Postman.
Pemetaan v1 ke v2
| API v1 | API v2 |
|---|---|
POST /api/v1/send | POST /api/v2/send |
Token di parameter api_token | Token di header Authorization: Bearer atau X-Api-Token |
Body form (http_build_query) | Body JSON |
{"status":"success","response":"Mail Sent"} | {"success":true,"data":{"message_id":"…"}} |
| Tidak ada message_id di respons | message_id dikembalikan untuk pelacakan webhook |
Error tetap HTTP 200 dengan status: failed | Error memakai kode HTTP (400, 401, 402, 403, 422, 429) |
Panduan Terkait
Masih butuh bantuan?
Tim support Mailketing siap membantu setup domain, SMTP, maupun integrasi API melalui WhatsApp atau email.

Gmana nerapin di google aps Script mas? email penerima dan isi email ada di google spreadsheet.
pake zapier aja, cek di tutorial zapier
mau tanya,, apakah ada api untuk nambah whitelabel sender nya?
tidak ada