Email API Documentation

Base URL: https://api.ion.net.id

Konsep Integrasi

Portal ini memakai model API key + mailbox credential dari CMS. Dashboard hanya membuat API key dan izin mailbox. Password mailbox tetap disimpan di CMS, lalu dikirim ke API saat membaca atau membalas email.

CMS mengirim Authorization: Bearer API_KEY.
CMS memilih mailbox, misalnya billing@ion.net.id.
CMS mengirim mailbox_password milik mailbox tersebut.
Portal mencoba login IMAP/SMTP memakai mailbox + password itu.
Jika password salah, API mengembalikan mailbox_auth_failed.

Dengan model ini, portal tidak menyimpan password email. CMS cukup menyimpan API key, alamat mailbox, dan password mailbox.

Setup Singkat

Login ke dashboard: https://api.ion.net.id/login.
Pilih domain Virtualmin/Webmin dari form Generate API Key.
Pilih mailbox yang muncul otomatis dari domain tersebut.
Pilih permission/rule API: read only, read + reply, atau full.
Klik generate, lalu simpan API key di CMS.
Di CMS, isi API key, alamat mailbox, dan password mailbox.

Authentication

Semua endpoint /api/v1 wajib memakai Bearer token.

Authorization: Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Endpoint yang membaca atau mengirim email juga membutuhkan password mailbox. Kirim salah satu cara berikut:

X-Mailbox-Password: password-email

atau di JSON body:

{
  "mailbox_password": "password-email"
}

Scopes

Scope	Fungsi
`emails:read`	Melihat daftar mailbox, daftar email, dan detail email.
`emails:reply`	Membalas email yang sudah ada melalui SMTP mailbox di portal.
`emails:send`	Mengirim email baru melalui SMTP mailbox di portal.
`mailboxes:create`	Membuat mailbox baru di domain Virtualmin/Webmin yang diizinkan.

Endpoints

GET  /api/v1/mailboxes
GET  /api/v1/mailboxes/{mailbox}/emails?limit=10&unseen=1
GET  /api/v1/mailboxes/{mailbox}/emails/{id}
POST /api/v1/mailboxes/{mailbox}/emails/{id}/reply
POST /api/v1/mailboxes/{mailbox}/send
POST /api/v1/domains/{domain}/mailboxes

Gunakan URL encoded untuk mailbox. Contoh: billing@ion.net.id menjadi billing%40ion.net.id.

1. List Mailboxes

curl https://api.ion.net.id/api/v1/mailboxes \
  -H "Authorization: Bearer ek_live_xxxxxxxxx"

{
  "data": [
    {
      "email": "billing@ion.net.id",
      "imap_host": "mail.ion.net.id",
      "smtp_host": "mail.ion.net.id"
    }
  ]
}

2. List Emails

curl "https://api.ion.net.id/api/v1/mailboxes/billing%40ion.net.id/emails?limit=10&unseen=1" \
  -H "Authorization: Bearer ek_live_xxxxxxxxx" \
  -H "X-Mailbox-Password: password-email"

{
  "data": [
    {
      "id": "12345",
      "from": "Customer <customer@example.com>",
      "to": "billing@ion.net.id",
      "subject": "Konfirmasi pembayaran",
      "date": "Fri, 19 Jun 2026 12:00:00 +0800",
      "message_id": "<abc@example.com>"
    }
  ]
}

3. Read Email Detail

curl https://api.ion.net.id/api/v1/mailboxes/billing%40ion.net.id/emails/12345 \
  -H "Authorization: Bearer ek_live_xxxxxxxxx" \
  -H "X-Mailbox-Password: password-email"

{
  "data": {
    "id": "12345",
    "from": "Customer <customer@example.com>",
    "subject": "Konfirmasi pembayaran",
    "message_id": "<abc@example.com>",
    "references": "",
    "body_raw": "Saya sudah melakukan pembayaran..."
  }
}

4. Reply Email

Endpoint ini mengambil email asli via IMAP, membuat header thread, lalu mengirim balasan via SMTP memakai password mailbox yang dikirim CMS.

curl -X POST https://api.ion.net.id/api/v1/mailboxes/billing%40ion.net.id/emails/12345/reply \
  -H "Authorization: Bearer ek_live_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "mailbox_password":"password-email",
    "body":"Terima kasih, pembayaran Anda sedang kami proses."
  }'

{
  "ok": true
}

5. Create Mailbox

Endpoint ini membuat mailbox baru langsung di Virtualmin/Webmin. Gunakan API key dengan scope mailboxes:create.

curl -X POST https://api.ion.net.id/api/v1/domains/kliniktech.com/mailboxes \
  -H "Authorization: Bearer ek_live_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "local_part":"customer123",
    "password":"StrongPassword123",
    "real_name":"Customer 123",
    "quota":"50M"
  }'

{
  "ok": true,
  "data": {
    "email": "customer123@kliniktech.com",
    "username": "customer123@kliniktech.com",
    "domain": "kliniktech.com",
    "imap_host": "mail.kliniktech.com",
    "imap_port": 993,
    "smtp_host": "mail.kliniktech.com",
    "smtp_port": 465
  }
}

6. Send New Email

curl -X POST https://api.ion.net.id/api/v1/mailboxes/billing%40ion.net.id/send \
  -H "Authorization: Bearer ek_live_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "mailbox_password":"password-email",
    "to":"customer@example.com",
    "subject":"Informasi invoice",
    "body":"Invoice Anda sudah kami terbitkan."
  }'

Error Response

Status	Error	Arti
`401`	`unauthorized`	Bearer token tidak ada atau salah.
`401`	`mailbox_auth_failed`	Email mailbox atau password mailbox salah.
`403`	`forbidden`	Scope API key tidak cukup.
`403`	`mailbox_not_allowed`	API key tidak diizinkan mengakses mailbox tersebut.
`404`	`mailbox_not_found`	Mailbox belum didaftarkan di portal.
`422`	`invalid_request`	Payload tidak lengkap.
`422`	`mailbox_password_required`	Password mailbox belum dikirim oleh CMS.
`502`	`mail_server_error`	Koneksi IMAP/SMTP gagal atau server email menolak request.

Catatan Keamanan

API key hanya tampil sekali saat dibuat.
API key disimpan dalam bentuk hash.
Password mailbox tidak disimpan di portal. CMS mengirim password saat request.
Buat API key per CMS dan batasi mailbox serta scope-nya.
Gunakan scope emails:reply hanya untuk CMS yang memang boleh membalas email.

OpenAPI JSON