Cara Menambah Subscriber ke List via API (POST /subscribers)

Panduan ini untuk developer yang ingin memasukkan subscriber ke list Mailketing secara otomatis dari aplikasi, website, atau sistem sendiri. Caranya cukup satu request POST /subscribers di API v2.

Yang Perlu Disiapkan

• Akun Mailketing yang masih punya saldo kredit. Belum punya akun? Daftar di sini dan dapatkan 200 email credit gratis.
• API token dari menu Integrasi → Email Application API.
• List tujuan yang sudah dibuat (lihat Cara Membuat List di Mailketing) beserta ID List-nya.

Langkah-langkah Menambah Subscriber 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: Cari ID List tujuan

1. Buka Lists & Subscriber → Lihat Semua List.
2. Catat angka di kolom ID List untuk list yang dituju.
3. Atau ambil semua ID sekaligus lewat API: API Get All List from Account (GET /lists).

Langkah 3: Kirim request ke endpoint

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

Contoh cURL (minimal)

curl -X POST "https://api.mailketing.co.id/api/v2/subscribers" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN_ANDA" \
  -d '{
    "list_id": 1,
    "email": "[email protected]"
  }'

Contoh cURL (semua field)

curl -X POST "https://api.mailketing.co.id/api/v2/subscribers" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN_ANDA" \
  -d '{
    "list_id": 1,
    "email": "[email protected]",
    "first_name": "Budi",
    "last_name": "Santoso",
    "mobile": "08123456789",
    "birth_date": "1990-01-15",
    "city": "Jakarta",
    "state": "DKI Jakarta",
    "country": "Indonesia",
    "company": "Toko Budi",
    "post_code": "12345",
    "title": "Bapak",
    "phone": "021123456",
    "fax": "021123457"
  }'

Contoh PHP

<?php
$apiToken = 'TOKEN_ANDA'; // dari menu Integrasi → Email Application API

$data = [
    'list_id'    => 1,                        // ID List tujuan
    'email'      => '[email protected]',
    'first_name' => 'Budi',
    'mobile'     => '08123456789',            // kirim sebagai teks, bukan angka
];

$ch = curl_init('https://api.mailketing.co.id/api/v2/subscribers');
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        => 30,
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($response, true);
if (!empty($result['success'])) {
    echo 'Berhasil: ' . $result['data']['status']; // added atau already_exists
} 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 tambahSubscriber() {
  const res = await fetch('https://api.mailketing.co.id/api/v2/subscribers', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${apiToken}`,
    },
    body: JSON.stringify({
      list_id: 1,
      email: '[email protected]',
      first_name: 'Budi',
      mobile: '08123456789',
    }),
  });
  const result = await res.json();
  if (result.success) {
    console.log('Berhasil:', result.data.status); // added atau already_exists
  } else {
    console.error('Gagal', res.status, result.message, result.errors || '');
  }
}

tambahSubscriber();

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/subscribers",
    headers={"Authorization": f"Bearer {api_token}"},
    json={
        "list_id": 1,
        "email": "[email protected]",
        "first_name": "Budi",
        "mobile": "08123456789",
    },
    timeout=30,
)
result = resp.json()
if result.get("success"):
    print("Berhasil:", result["data"]["status"])  # added atau already_exists
else:
    print("Gagal", resp.status_code, result.get("message"), result.get("errors"))

Daftar Field

Semua field selain list_id dikirim sebagai teks (string). Angka seperti nomor HP harus diberi tanda kutip, misalnya "mobile": "08123456789". Bila dikirim sebagai angka, API menolak dengan pesan Mobile must be a string.

Custom field

Jika list punya custom field, kirim dengan nama field sebagai key dan isinya sebagai teks, contohnya "alamat_lengkap": "Jl. Sudirman No. 1". Custom field dibuat lewat Cara Membuat Custom Field di Mailketing.

Format nomor HP otomatis

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).

Subscriber baru berhasil ditambahkan (HTTP 200)

{
  "success": true,
  "data": {
    "email_list_id": 123,
    "list_id": 1,
    "status": "added"
  },
  "message": "Subscriber added to list 1"
}

Email sudah ada di list tersebut (HTTP 200, bukan error)

{
  "success": true,
  "data": {
    "email_list_id": null,
    "list_id": 1,
    "status": "already_exists"
  },
  "message": "Subscriber already in list 1"
}

Contoh error validasi (HTTP 422)

{
  "success": false,
  "data": null,
  "message": "Validation failed",
  "errors": {
    "email": "Email must be a valid email",
    "mobile": "Mobile must be a string"
  }
}

Contoh list tidak ditemukan (HTTP 404)

{
  "success": false,
  "data": null,
  "message": "List not found or access denied"
}

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. Pastikan respons berisi "success": true dan status bernilai added.
2. Buka Lists & Subscriber → Lihat Semua Subscriber dan cari email yang baru dikirim.
3. Jika status already_exists, email itu memang sudah ada di list sehingga tidak ditambahkan lagi.

Pertanyaan yang Sering Diajukan

Apakah subscriber dari API ikut menerima autoresponder?

Ya. Subscriber baru dari API diproses sama seperti subscriber dari form: autoresponder list, rules, dan webhook New Subscriber ikut berjalan. Jika statusnya already_exists, proses itu tidak diulang. Atur emailnya di Cara Membuat Autoresponder di Mailketing.

Kenapa muncul error 402 padahal saya hanya menambah subscriber?

API v2 memeriksa saldo di setiap request. Jika saldo kredit 0, semua endpoint menjawab Insufficient credits. Isi kredit lewat Pembayaran → Isi Kredit.

Data nama saya berubah, tanda baca hilang. Kenapa?

Untuk first_name dan last_name, karakter selain huruf, angka, dan spasi diganti spasi. Contohnya “Budi.S” tersimpan sebagai “Budi S”.

Bolehkah memanggil API ini langsung dari JavaScript di halaman website?

Sebaiknya tidak, karena token akan terlihat oleh siapa pun yang membuka halaman. Kirim data form ke server Anda dulu, lalu server yang memanggil API Mailketing.

Masih Memakai API v1?

Catatan: API v1 masih berfungsi untuk integrasi lama. Untuk integrasi baru, gunakan API v2 seperti di atas.

Parameter v1

• [api_token]: didapatkan di menu Integrasi → Email Application API.
• [list_id]: nomor/ID List.
• [email]: email subscriber.
• [first_name]: nama depan subscriber.
• [last_name]: nama belakang subscriber.
• [city]: kota.
• [state]: provinsi.
• [country]: negara.
• [company]: nama perusahaan.
• [phone]: nomor kantor.
• [mobile]: nomor handphone.

Contoh PHP (v1)

<?php
$api_token='isi_api_token'; //silahkan copy dari api token mailketing
$first_name='fadli'; //nama pengirim
$email='[email protected]'; //email pengirim
$list_id='1';
$params = [
'first_name' => $first_name,
'email' => $email,
'api_token' => $api_token,
'list_id' => $list_id
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,"https://api.mailketing.co.id/api/v1/addsubtolist");
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

{"response":"Added to List 1","status":true}

Contoh di versi lama dokumen ini menulis {"status":"success","response":"Added to List"}. Respons v1 yang berlaku sekarang seperti di atas: status bernilai true dan pesan menyertakan ID list. Pesan gagal v1 antara lain Access Denied, API TOKEN / LIST ID / EMAIL NOT FOUND, User Not Found or Wrong API Token, dan List Not Found.

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

Pemetaan v1 ke v2

Panduan Terkait

• API Get All List from Account
• Cara Kirim Email via API Mailketing (POST /send)
• Webhook Mailketing
• Cara Membuat List di Mailketing

Dokumentasi interaktif API v2: https://api.mailketing.co.id/docs/