Dokumentasi API

Email Sender

Integrasikan Email Sender dengan aplikasi eksternal — kelola kontak dan kirim email transaksional.

Semua endpoint
Belum ada API key. Buat key di Pengaturan → API Keys sebelum memanggil endpoint. Pengaturan → API Keys
https://instan.app/api/v1
Semua endpoint diawali dengan prefix berikut.

Autentikasi

Setiap request wajib menyertakan API key dari Pengaturan.

Format key: inst_... (dibuat sekali, disimpan di tempat aman).

Header Nilai Keterangan
Authorization Bearer {email_api_key} Disarankan
X-API-Key {email_api_key} Alternatif
Content-Type application/json Wajib untuk POST

Daftar Contact List

Mengembalikan semua contact list milik akun Anda beserta jumlah kontak.

GET https://instan.app/api/v1/lists
curl --request GET \
--url 'https://instan.app/api/v1/lists' \
--header 'Authorization: Bearer {email_api_key}' 
{
    "success": true,
    "data": [
        {
            "id": 5,
            "name": "Newsletter",
            "description": null,
            "contact_count": 128,
            "created_at": "2026-06-01 10:00:00"
        }
    ]
}

Tambah Kontak ke List

Menambahkan kontak ke list tertentu. Jika email sudah ada, data diperbarui. Kontak otomatis di-enroll ke series (jika ada) dan funnel rules dijalankan.

POST https://instan.app/api/v1/lists/{list_id}/contacts
curl --request POST \
--url 'https://instan.app/api/v1/lists/5/contacts' \
--header 'Authorization: Bearer {email_api_key}' \
--header 'Content-Type: application/json' \
--data '{"email":"john@example.com","first_name":"John"}'
Parameter Rincian Deskripsi
email Diperlukan String Alamat email kontak
first_name Opsional String Nama depan
last_name Opsional String Nama belakang
custom_fields Opsional object Field custom sesuai schema list (lihat Kontak → Lists → Edit) 
{
    "success": true,
    "message": "Kontak berhasil ditambahkan.",
    "created": true,
    "data": {
        "id": 42,
        "list_id": 5,
        "email": "john@example.com",
        "first_name": "John",
        "last_name": null,
        "custom_fields": {},
        "status": "active",
        "subscribed_at": "2026-06-08 12:00:00"
    }
}
{
    "success": true,
    "message": "Kontak sudah ada — data diperbarui dan dipindahkan ke list ini.",
    "created": false,
    "data": {
        "id": 42,
        "list_id": 5,
        "email": "john@example.com"
    }
}

Daftar Domain Terverifikasi

Domain yang sudah terverifikasi dan bisa dipakai sebagai pengirim email API. Gunakan domain_id saat mengirim email.

GET https://instan.app/api/v1/domains
curl --request GET \
--url 'https://instan.app/api/v1/domains' \
--header 'Authorization: Bearer {email_api_key}' 
{
    "success": true,
    "data": [
        {
            "id": 3,
            "name": "mail.example.com",
            "from_email": "noreply@mail.example.com",
            "from_name": "Example Inc",
            "is_default": true
        }
    ]
}

Kirim Email

Mengirim satu email transaksional dari domain terverifikasi. Mencatat log pengiriman dan mendukung merge tag ({{first_name}}, dll.) jika penerima ada di kontak.

POST https://instan.app/api/v1/emails/send
curl --request POST \
--url 'https://instan.app/api/v1/emails/send' \
--header 'Authorization: Bearer {email_api_key}' \
--header 'Content-Type: application/json' \
--data '{"to":"customer@example.com","subject":"Notifikasi","html_body":"<p>Halo</p>"}'
Parameter Rincian Deskripsi
to Diperlukan String Email penerima
subject Diperlukan String Subjek email (boleh merge tag)
html_body Diperlukan String Isi email format HTML
plain_body Opsional String Versi plain-text (opsional)
domain_id Opsional Integer Domain pengirim; default = domain utama terverifikasi
from_name Opsional String Override nama pengirim
reply_to Opsional String Alamat balasan (default: email akun)
contact_id Opsional Integer ID kontak untuk merge tag khusus
merge Opsional Boolean Proses merge tag (default: true)
track Opsional Boolean Tracking open/click (default: true)
tag Opsional String Tag Postal (default: api) 
{
    "success": true,
    "message": "Email berhasil dikirim.",
    "data": {
        "log_id": 901,
        "message_id": 123456,
        "token": "abc123",
        "from_email": "noreply@mail.example.com",
        "from_name": "Example Inc",
        "to": "customer@example.com",
        "domain_id": 3,
        "tracking_token": "a1b2c3..."
    }
}

Kode Error

HTTP Penyebab
401 API key tidak ada, salah, atau tidak valid
404 Contact list list_id tidak ditemukan
422 Validasi gagal (email, subject, domain, kontak unsubscribe, dll.)
502 Mail server menolak pengiriman

Alur integrasi

Langkah disarankan untuk setup pertama kali

  1. Verifikasi domain di menu Pengaturan → Pengirim.
  2. Buat API key di Pengaturan → Umum → API Keys.
  3. Panggil GET /domains dan GET /lists untuk verifikasi koneksi.
  4. Sinkronkan kontak via POST /lists/{id}/contacts.
  5. Kirim email transaksional via POST /emails/send.