TempMailCloudflare Native
Dokumentasi API

Panduan lengkap TempMail API untuk developer dan integrator.

A complete TempMail API guide for developers and integrators.

Halaman ini menjelaskan request, response, error response, autentikasi, dan contoh penggunaan endpoint penting di aplikasi TempMail berbasis Cloudflare.

Bahasa
OpenAPI JSON

Gambaran umum

Ringkasan singkat tentang cara kerja API TempMail dan pola response yang dipakai di semua endpoint.

Format response umum

{
  "success": true,
  "data": {}
}
{
  "success": false,
  "error": "Readable error message"
}

Autentikasi yang dipakai

  • Inbox memakai Authorization: Bearer <accessToken>.
  • Admin memakai cookie session hasil login /api/admin/login.
  • Protected inbox bisa dibuka lagi lewat /api/inboxes/access atau /api/inboxes/:id/unlock.

Public & inbox API

Endpoint untuk domain, pembuatan inbox, login protected inbox, membaca email, memperpanjang inbox, dan manajemen inbox.

GET /api/domains
Tanpa autentikasi

Ambil daftar domain aktif yang tersedia untuk pembuatan inbox.

Dipakai halaman utama untuk mengisi dropdown domain. Hanya domain aktif dari D1 yang akan dikembalikan.

Contoh penggunaan

curl -X GET https://tempmail.example.com/api/domains

Success response

{
  "success": true,
  "data": [
    { "domain": "mail.bsmart.my.id", "isDefault": true },
    { "domain": "alt-mail.bsmart.my.id", "isDefault": false }
  ]
}

Error response umum

500 Server gagal membaca domain 
{
  "success": false,
  "error": "Readable error message"
}

Catatan implementasi

  • Tidak memerlukan token inbox atau cookie admin.
POST /api/inboxes
Tanpa autentikasi

Buat inbox baru, temporary 24 jam atau protected lifetime.

Jika `password` kosong maka inbox bersifat temporary. Jika `password` diisi maka inbox menjadi protected lifetime.

Body request

{
  "username": "demo",
  "domain": "mail.bsmart.my.id",
  "password": ""
}

Contoh penggunaan

curl -X POST https://tempmail.example.com/api/inboxes \
  -H "Content-Type: application/json" \
  -d '{"username":"demo","domain":"mail.bsmart.my.id","password":""}'

Success response

{
  "success": true,
  "data": {
    "id": "inb_abc123456789",
    "address": "demo@mail.bsmart.my.id",
    "accessToken": "eyJhbGciOi...",
    "isProtected": false,
    "isLifetime": false,
    "expiresAt": "2026-04-18T01:15:00.000Z"
  }
}

Error response umum

400 Body request tidak valid 
{
  "success": false,
  "error": "Selected domain is not available"
}
429 Rate limit pembuatan inbox 
{
  "success": false,
  "error": "Too many inboxes created, please slow down"
}

Catatan implementasi

  • Simpan `accessToken` karena dipakai untuk membaca email dan aksi inbox selanjutnya.
POST /api/inboxes/access
Tanpa autentikasi

Masuk kembali ke protected inbox menggunakan alamat email inbox dan password.

Dipakai saat token protected inbox hilang. Server akan memverifikasi password dan mengeluarkan access token baru.

Body request

{
  "address": "demo@mail.bsmart.my.id",
  "password": "super-secret-password"
}

Contoh penggunaan

curl -X POST https://tempmail.example.com/api/inboxes/access \
  -H "Content-Type: application/json" \
  -d '{"address":"demo@mail.bsmart.my.id","password":"super-secret-password"}'

Success response

{
  "success": true,
  "data": {
    "id": "inb_abc123456789",
    "address": "demo@mail.bsmart.my.id",
    "accessToken": "eyJhbGciOi...",
    "isProtected": true,
    "isLifetime": true,
    "expiresAt": null
  }
}

Error response umum

401 Password salah atau inbox tidak ditemukan 
{
  "success": false,
  "error": "Invalid password"
}
429 Terlalu banyak percobaan login inbox 
{
  "success": false,
  "error": "Too many access attempts"
}
GET /api/inboxes/:id
Optional Bearer token

Ambil metadata inbox dan status aksesnya.

Untuk inbox protected tanpa token valid, endpoint ini tetap berguna karena akan memberi tahu bahwa inbox sedang locked.

Contoh penggunaan

curl -X GET https://tempmail.example.com/api/inboxes/inb_abc123456789

Success response

{
  "success": true,
  "data": {
    "id": "inb_abc123456789",
    "address": "demo@mail.bsmart.my.id",
    "isProtected": true,
    "isLifetime": true,
    "status": "active",
    "expiresAt": null,
    "messageCount": 4,
    "locked": true,
    "accessGranted": false,
    "canExtend": false
  }
}

Error response umum

404 Inbox tidak ditemukan 
{
  "success": false,
  "error": "Inbox not found"
}
410 Inbox temporary sudah expired 
{
  "success": false,
  "error": "Inbox expired"
}
GET /api/inboxes/:id/messages
Bearer token inbox

Ambil daftar pesan milik inbox tertentu.

Gunakan query `q` untuk pencarian sender, subject, atau isi email. Endpoint ini dipakai untuk panel daftar email di UI inbox.

Query parameter

q=facebook

Contoh penggunaan

curl -X GET "https://tempmail.example.com/api/inboxes/inb_abc123456789/messages?q=facebook" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Success response

{
  "success": true,
  "data": [
    {
      "id": "msg_1",
      "senderEmail": "registration@facebookmail.com",
      "subject": "15446 is your confirmation code",
      "receivedAt": "2026-04-17T01:07:51.000Z",
      "status": "unread"
    }
  ]
}

Error response umum

401 Token tidak valid 
{
  "success": false,
  "error": "Access denied"
}
423 Inbox protected masih terkunci 
{
  "success": false,
  "error": "Inbox is locked"
}
GET /api/messages/:id
Bearer token inbox

Ambil detail lengkap satu email.

Response berisi text body, sanitized HTML, attachment metadata, dan data ekstraksi lain yang dibutuhkan UI.

Contoh penggunaan

curl -X GET https://tempmail.example.com/api/messages/msg_1 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Success response

{
  "success": true,
  "data": {
    "id": "msg_1",
    "inboxId": "inb_abc123456789",
    "senderEmail": "registration@facebookmail.com",
    "senderName": "Facebook",
    "subject": "15446 is your confirmation code",
    "textBody": "15446 is your confirmation code",
    "htmlBody": "...
",
    "attachments": [],
    "receivedAt": "2026-04-17T01:07:51.000Z"
  }
}

Error response umum

404 Pesan tidak ditemukan 
{
  "success": false,
  "error": "Message not found"
}
401 Akses ditolak 
{
  "success": false,
  "error": "Access denied"
}
POST /api/inboxes/:id/unlock
Password inbox

Buka protected inbox menggunakan password.

Setelah berhasil, endpoint ini memutar access token baru. Cocok dipakai dari halaman inbox ketika status inbox masih locked.

Body request

{
  "password": "super-secret-password"
}

Contoh penggunaan

curl -X POST https://tempmail.example.com/api/inboxes/inb_abc123456789/unlock \
  -H "Content-Type: application/json" \
  -d '{"password":"super-secret-password"}'

Success response

{
  "success": true,
  "data": {
    "id": "inb_abc123456789",
    "accessToken": "eyJhbGciOi...",
    "expiresAt": null,
    "isProtected": true,
    "isLifetime": true
  }
}

Error response umum

401 Password salah atau inbox tidak aktif 
{
  "success": false,
  "error": "Invalid password"
}
429 Terlalu banyak percobaan unlock 
{
  "success": false,
  "error": "Too many unlock attempts"
}
POST /api/inboxes/:id/extend
Bearer token inbox temporary

Perpanjang masa aktif inbox temporary.

Durasi yang diizinkan adalah `24h`, `3d`, dan `7d`. Protected lifetime inbox tidak bisa di-extend.

Body request

{
  "duration": "24h"
}

Contoh penggunaan

curl -X POST https://tempmail.example.com/api/inboxes/inb_abc123456789/extend \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"duration":"24h"}'

Success response

{
  "success": true,
  "data": {
    "id": "inb_abc123456789",
    "expiresAt": "2026-04-19T01:15:00.000Z",
    "extendedCount": 1
  }
}

Error response umum

400 Inbox tidak memenuhi syarat extend 
{
  "success": false,
  "error": "Permanent inbox does not require extension"
}
401 Token tidak valid 
{
  "success": false,
  "error": "Access denied"
}
DELETE /api/inboxes/:id
Bearer token inbox

Hapus inbox beserta semua email dan metadata terkait.

Aksi ini mem-purge email, attachment reference, dan token akses. Tidak bisa di-undo.

Contoh penggunaan

curl -X DELETE https://tempmail.example.com/api/inboxes/inb_abc123456789 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Success response

{
  "success": true,
  "data": {
    "deleted": true
  }
}

Error response umum

401 Tidak punya akses ke inbox 
{
  "success": false,
  "error": "Access denied"
}

Realtime API

Endpoint untuk update inbox realtime melalui long-poll dan WebSocket.

GET /api/inboxes/:id/wait?timeout=30&since=cursor
Bearer token inbox

Long-poll untuk menunggu email baru.

Pakai endpoint ini kalau kamu tidak ingin menggunakan WebSocket. Worker akan menunggu sampai timeout atau ada event baru.

Query parameter

timeout=1..30, since=

Contoh penggunaan

curl -X GET "https://tempmail.example.com/api/inboxes/inb_abc123456789/wait?timeout=30" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Success response

{
  "success": true,
  "data": {
    "hasUpdate": true,
    "cursor": "1713322800",
    "type": "message.received"
  }
}

Error response umum

401 Token tidak valid 
{
  "success": false,
  "error": "Readable error message"
}
GET /ws/inboxes/:id?token=
Token inbox via query/header

WebSocket realtime untuk event inbox.

Ketika email baru selesai diproses, Durable Object inbox room akan mendorong event `message.received` ke koneksi aktif.

Contoh penggunaan

const socket = new WebSocket(
  "wss://tempmail.example.com/ws/inboxes/inb_abc123456789?token=YOUR_ACCESS_TOKEN"
);

Success response

{
  "type": "message.received",
  "messageId": "msg_1",
  "receivedAt": "2026-04-17T02:20:00.000Z"
}

Error response umum

401 Koneksi ditolak 
{
  "success": false,
  "error": "Readable error message"
}

Catatan implementasi

  • Direkomendasikan untuk UI inbox realtime. Untuk fallback sederhana gunakan `/wait`.