Dokumentasi API

REST API sederhana untuk membuat email sementara, membaca pesan, dan menghapusnya — cocok untuk bot & otomasi. Semua respons berformat JSON. Endpoint bot bisa ditembak langsung tanpa session.

Base URL

https://mail.contoh.com

Autentikasi
Daftar Domain
Generate Email
Daftar Pesan
Tunggu Pesan (Real-time)
Baca Pesan
Hapus Pesan
Kosongkan Inbox

Autentikasi

Secara default endpoint /api/bot/* terbuka. Jika server menyetel BOT_TOKEN di .env, sertakan token pada setiap permintaan lewat salah satu header berikut:

Authorization: Bearer <BOT_TOKEN>
# atau
x-bot-token: <BOT_TOKEN>

Tanpa token yang benar (saat BOT_TOKEN aktif), API membalas 401 {"ok":false,"error":"Token bot tidak valid."}.

GET /api/bot/domains

Mengambil daftar domain aktif yang bisa dipakai untuk membuat alamat, beserta domain utama (primary).

Contoh cURL

curl https://mail.contoh.com/api/bot/domains

Respons

{
  "ok": true,
  "primary": "contoh.com",
  "domains": ["contoh.com"]
}

POST /api/bot/inbox

Membuat alamat email sementara baru secara acak. Bisa memilih domain tertentu lewat body JSON atau query ?domain=; jika tidak, dipakai domain utama.

Parameter (opsional)

Nama	Lokasi	Keterangan
`domain`	body / query	Domain target. Harus salah satu dari `/api/bot/domains`. Default: domain utama.

Contoh cURL

curl -X POST https://mail.contoh.com/api/bot/inbox \
  -H "Content-Type: application/json" \
  -d '{"domain":"contoh.com"}'

Respons

{
  "ok": true,
  "address": "ab12cd34ef@contoh.com",
  "domain": "contoh.com",
  "ttlMinutes": 60
}

ttlMinutes = berapa menit pesan disimpan sebelum dihapus otomatis.

GET /api/bot/inbox/{address}

Mengambil daftar pesan pada sebuah inbox (terbaru di atas). Hanya ringkasan + preview teks; gunakan endpoint baca untuk isi lengkap.

Contoh cURL

curl https://mail.contoh.com/api/bot/inbox/ab12cd34ef@contoh.com

Respons

{
  "ok": true,
  "address": "ab12cd34ef@contoh.com",
  "count": 1,
  "messages": [
    {
      "id": "HNqtOlUvoZUM0hCGrmoW1",
      "sender": "noreply@contoh.com",
      "fromName": "Contoh",
      "subject": "Kode verifikasi kamu",
      "preview": "Kode OTP kamu adalah 123456 ...",
      "receivedAt": 1782288624436,
      "seen": false
    }
  ]
}

GET /api/bot/inbox/{address}/wait

Long-poll: koneksi ditahan sampai ada pesan BARU masuk, lalu langsung dibalas saat itu juga (mirip Telegram, ~1 detik). Ideal untuk bot OTP tanpa polling boros.

Parameter (opsional)

Nama	Lokasi	Keterangan
`timeout`	query	Detik menunggu sebelum menyerah (default 25, maks 110).
`sinceId`	query	ID pesan terakhir yang sudah diproses. Jika ada pesan lebih baru, langsung dibalas tanpa menunggu.
`since`	query	Timestamp (ms). Alternatif `sinceId`: balas jika ada pesan setelah waktu ini.

Contoh cURL

curl "https://mail.contoh.com/api/bot/inbox/ab12cd34ef@contoh.com/wait?timeout=30"

Respons (ada pesan)

{
  "ok": true,
  "message": {
    "id": "HNqtOlUvoZUM0hCGrmoW1",
    "sender": "noreply@contoh.com",
    "subject": "Kode verifikasi kamu",
    "receivedAt": 1782288624436
  }
}

Respons (timeout, tidak ada pesan)

{ "ok": true, "message": null, "timedOut": true }

Saat dapat timedOut: true, cukup panggil ulang endpoint ini (gunakan sinceId dari pesan terakhir agar tidak ada yang terlewat).

GET /api/bot/inbox/{address}/messages/{id}

Membaca isi lengkap satu pesan (teks & HTML) beserta daftar lampiran. Secara default TIDAK menandai pesan sebagai dibaca.

Parameter (opsional)

Nama	Lokasi	Keterangan
`markSeen`	query	Set `1` atau `true` untuk menandai pesan sudah dibaca.

Contoh cURL

curl https://mail.contoh.com/api/bot/inbox/ab12cd34ef@contoh.com/messages/HNqtOlUvoZUM0hCGrmoW1

Respons

{
  "ok": true,
  "id": "HNqtOlUvoZUM0hCGrmoW1",
  "sender": "noreply@contoh.com",
  "fromName": "Contoh",
  "subject": "Kode verifikasi kamu",
  "text": "Kode OTP kamu adalah 123456",
  "html": "<p>Kode OTP kamu adalah <b>123456</b></p>",
  "receivedAt": 1782288624436,
  "attachments": [
    { "id": "x1", "filename": "invoice.pdf", "contentType": "application/pdf", "size": 20480 }
  ]
}

Unduh lampiran lewat endpoint web yang sudah ada: /api/inbox/{address}/messages/{id}/attachments/{attId}.

DELETE /api/bot/inbox/{address}/messages/{id}

Menghapus satu pesan dari inbox.

Contoh cURL

curl -X DELETE https://mail.contoh.com/api/bot/inbox/ab12cd34ef@contoh.com/messages/HNqtOlUvoZUM0hCGrmoW1

Respons

{ "ok": true, "deleted": true }

DELETE /api/bot/inbox/{address}

Mengosongkan seluruh pesan pada sebuah inbox.

Contoh cURL

curl -X DELETE https://mail.contoh.com/api/bot/inbox/ab12cd34ef@contoh.com

Respons

{ "ok": true, "deleted": 3 }

Kode status

Kode	Arti
`200`	Sukses.
`400`	Alamat tidak valid (format salah atau domain tidak aktif).
`401`	Token bot tidak valid (saat `BOT_TOKEN` aktif).
`404`	Pesan tidak ditemukan.