Langsung ke konten

Cara Kirim Email via API Mailketing — Dokumentasi Lengkap (POST /send)

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 Setup Domain → Tambah Domain. Panduannya: Whitelabel Sender (Cloudflare) atau Whitelabel Sender (cPanel).
  • API token dari menu Integrasi → Email Application API.

Langkah-langkah Kirim Email via API

Langkah 1: Ambil API token

  1. Masuk ke dashboard di be.mailketing.co.id/login.
  2. Buka menu Integrasi → Email Application API.
  3. Di kotak Konfigurasi API, klik tombol Salin di samping kolom API Token.

Penting: Tombol Generate Token Baru 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 Setup 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

BagianNilai
MethodPOST
URLhttps://api.mailketing.co.id/api/v2/send
HeaderContent-Type: application/json dan Authorization: Bearer TOKEN_ANDA
BodyJSON berisi from_name, from_email, subject, recipient, content

Token juga bisa dikirim dengan cara lain. Pilih salah satu saja:

Cara mengirim tokenContoh
Header Authorization (disarankan)Authorization: Bearer TOKEN_ANDA
Header X-Api-TokenX-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 Integrasi → Email Application API

$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

FieldWajibTipeKeterangan
from_nameYateks (maks. 255)Nama pengirim yang tampil di kotak masuk.
from_emailYaemail (maks. 255)Email pengirim. Domainnya harus sudah ditambahkan dan aktif di menu Setup Domain.
subjectYateks (maks. 998)Judul email.
recipientYaemail (maks. 255)Alamat email penerima. Satu request untuk satu penerima.
contentYateksIsi email. HTML (mengandung tag <html>) tidak dibatasi ukurannya; teks biasa maksimal 300 KB.
attach1, attach2, attach3TidakURLLink 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"
  }
}
HTTPPesanPenyebab
400Invalid attach1: …URL lampiran tidak aman/bukan URL publik, atau file lebih dari 25 MB.
401Missing API token / Invalid API tokenToken tidak dikirim atau salah.
402Insufficient credits / No credits. Please top up.Saldo kredit habis. Isi kredit dulu.
403Unknown sender domain…Domain from_email belum ditambahkan atau belum aktif di Setup Domain.
422Validation failedAda field kosong atau salah format. Detailnya di errors.
429Rate limit exceededTerlalu 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

  1. Kirim email uji ke alamat Anda sendiri.
  2. Pastikan respons berisi "success": true dan ada message_id.
  3. Cek kotak masuk (dan folder spam/promosi) di alamat tujuan.
  4. Jika memakai webhook, pastikan event open/bounce yang masuk membawa message_id yang 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 Setup 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.

BagianNilai (v1)
URLhttps://api.mailketing.co.id/api/v1/send
MethodPOST
FormatForm (application/x-www-form-urlencoded) atau JSON. Token dikirim sebagai parameter api_token.

Parameter v1

  • [api_token]: didapatkan di menu Integrasi → Email Application API.
  • [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"}
StatusResponseDeskripsi
successMail SentEmail diterima untuk dikirim ke tujuan.
failedUser Not Found or Wrong API TokenUser Mailketing tidak ditemukan atau API token salah (juga muncul jika saldo kredit 0).
failedAccess Denied, Invalid TokenToken tidak diisi.
failedUnknown Sender, Please Add your Sender Email at Add Domain MenuEmail pengirim belum ditambahkan di menu Setup Domain. Tambahkan dulu.
failedEmpty From NameFrom Name kosong.
failedNo Credits, Please Top UpKredit habis. Silakan isi kredit dulu.
failedEmpty Recipient, Please Add recipient addressEmail penerima tidak diisi.
failedBlacklistedEmail penerima masuk blacklist karena tidak valid, palsu (fake), sekali pakai (disposable), atau email spam.
failedEmpty Subject, Please Add Subject EmailSubject kosong.
failedEmpty Content, Please Add Email ContentIsi email kosong.
failedOversize Content, Reduce Content below 300kbKonten teks biasa lebih dari 300 KB.

Koleksi Postman lama (API v1): Run in Postman.

Pemetaan v1 ke v2

API v1API v2
POST /api/v1/sendPOST /api/v2/send
Token di parameter api_tokenToken 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 responsmessage_id dikembalikan untuk pelacakan webhook
Error tetap HTTP 200 dengan status: failedError memakai kode HTTP (400, 401, 402, 403, 422, 429)

Panduan Terkait

Apakah artikel ini membantu?

Masih butuh bantuan?

Tim support Mailketing siap membantu setup domain, SMTP, maupun integrasi API melalui WhatsApp atau email.

4 Responses

Tinggalkan Balasan

Alamat email Anda tidak akan dipublikasikan. Ruas yang wajib ditandai *