BLTZMAIL BLTZMAIL DEVELOPER DOCUMENTATION
Kembali ke BLTZMAIL
DOKUMENTASI API
Overview Authentication Health Check Mailbox Messages Attachments Webhooks Delivery & Retry Error Codes Node.js Example
BLTZMAIL DEVELOPER PLATFORM

API untuk mailbox sementara, pesan, attachment dan webhook.

BLTZMAIL API memungkinkan aplikasi, bot, backend, automation, atau sistem internal membuat temporary mailbox, membaca email secara real-time, mengambil attachment, serta menerima event melalui webhook.

API VERSION V1 DOMAIN bltzmail.biz.id JSON REST API WEBHOOK HMAC SHA-256
BASE URL

Endpoint utama

Request API menggunakan domain BLTZMAIL yang sama.

Production
https://bltzmail.biz.id/api/v1
AUTHENTICATION

Dua jenis autentikasi.

API Key Digunakan oleh integrasi eksternal saat membuat mailbox. Header yang digunakan adalah x-api-bltzmail.
Mailbox Access Token Token khusus mailbox. Digunakan sebagai Bearer Token untuk membaca pesan, attachment, webhook, dan menghapus mailbox.

API Key Header

HTTP Header
x-api-bltzmail: YOUR_API_KEY

Mailbox Bearer Token

HTTP Header
Authorization: Bearer YOUR_ACCESS_TOKEN
Access token mailbox hanya dikembalikan saat mailbox dibuat. Simpan token secara aman. Server menyimpan hash token, bukan token plaintext.
SYSTEM

Health Check

GET /api/v1/health

Memeriksa status API dan koneksi database.

Response
{
  "success": true,
  "service": "BLTZMAIL API",
  "status": "online",
  "database": "online",
  "version": "1.1.0",
  "timestamp": "2026-08-28T00:00:00.000Z"
}
MAILBOX API

Mailbox

Mailbox adalah alamat temporary email BLTZMAIL. Setiap mailbox memiliki ID dan access token tersendiri.

POST /api/v1/mailboxes

Membuat mailbox baru. Username dapat dikirim manual atau dikosongkan untuk menghasilkan nama acak.

AUTH: LOGIN USER ATAU x-api-bltzmail
Request
curl -X POST \
  https://bltzmail.biz.id/api/v1/mailboxes \
  -H "Content-Type: application/json" \
  -H "x-api-bltzmail: YOUR_API_KEY" \
  -d '{
    "username": "mybot"
  }'
201 Response
{
  "success": true,
  "data": {
    "mailboxId": "uuid",
    "email": "mybot@bltzmail.biz.id",
    "username": "mybot",
    "domain": "bltzmail.biz.id",
    "status": "active",
    "accessToken": "64-character-token",
    "createdAt": "...",
    "expiresAt": "..."
  }
}
GET /api/v1/mailboxes

Mengambil daftar mailbox milik akun yang sedang login.

AUTH: USER SESSION
Integrasi API key dapat membuat mailbox, tetapi mailbox API-client tidak memiliki user_id. Karena itu daftar mailbox user ditujukan terutama untuk akun website.
GET /api/v1/mailboxes/:id

Mengambil detail mailbox, jumlah pesan, jumlah unread, waktu dibuat, dan waktu kedaluwarsa.

AUTH: MAILBOX BEARER TOKEN
Request
curl \
  https://bltzmail.biz.id/api/v1/mailboxes/MAILBOX_ID \
  -H "Authorization: Bearer ACCESS_TOKEN"
DELETE /api/v1/mailboxes/:id

Menghapus mailbox beserta resource yang terhubung melalui relasi database.

AUTH: MAILBOX BEARER TOKEN
MESSAGE API

Messages

GET /api/v1/mailboxes/:id/messages

Mengambil maksimal 100 pesan terbaru dari mailbox.

AUTH: MAILBOX BEARER TOKEN
Response Data
{
  "success": true,
  "data": {
    "mailboxId": "...",
    "email": "mybot@bltzmail.biz.id",
    "messages": [
      {
        "id": "...",
        "from": "sender@example.com",
        "fromName": "Sender",
        "subject": "Verification",
        "text": "Your code is 123456",
        "html": "<p>...</p>",
        "receivedAt": "...",
        "sizeBytes": 2048,
        "isRead": false
      }
    ]
  }
}
GET /api/v1/mailboxes/:id/messages/:messageId

Membaca detail satu pesan termasuk raw headers dan attachment. Saat endpoint ini dibuka, pesan otomatis ditandai sebagai dibaca.

AUTH: MAILBOX BEARER TOKEN
Endpoint detail melakukan update is_read = true.
DELETE /api/v1/mailboxes/:id/messages/:messageId

Menghapus satu pesan dari mailbox.

AUTH: MAILBOX BEARER TOKEN
ATTACHMENT API

Attachments

GET /api/v1/mailboxes/:id/messages/:messageId/attachments

Mengambil metadata attachment dari sebuah pesan.

AUTH: MAILBOX BEARER TOKEN
Field Keterangan
id ID attachment.
filename Nama file yang sudah disanitasi.
content_type MIME type attachment.
size_bytes Ukuran file dalam byte.
GET /api/v1/mailboxes/:id/messages/:messageId/attachments/:attachmentId

Mengunduh file attachment. Response dikirim sebagai file menggunakan Content-Disposition: attachment.

AUTH: MAILBOX BEARER TOKEN
WEBHOOK API

Mailbox Webhooks

Satu mailbox dapat memiliki maksimal lima webhook. Webhook akan menerima event ketika email baru berhasil masuk.

POST /api/v1/mailboxes/:id/webhooks

Mendaftarkan webhook pada mailbox.

AUTH: MAILBOX BEARER TOKEN
Request
curl -X POST \
  https://bltzmail.biz.id/api/v1/mailboxes/MAILBOX_ID/webhooks \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhook"
  }'
URL harus menggunakan HTTP atau HTTPS. URL yang sama tidak dapat didaftarkan dua kali pada mailbox yang sama. Maksimal 5 webhook/mailbox.
201 Response
{
  "success": true,
  "data": {
    "webhook": {
      "id": "...",
      "mailbox_id": "...",
      "url": "https://example.com/webhook",
      "secret": "whsec_...",
      "is_active": true,
      "created_at": "..."
    }
  }
}
Simpan secret webhook ketika webhook dibuat. Endpoint list tidak mengembalikan secret.
GET /api/v1/mailboxes/:id/webhooks

Mengambil seluruh webhook yang terikat langsung pada mailbox.

AUTH: MAILBOX BEARER TOKEN
DELETE /api/v1/mailboxes/:id/webhooks/:webhookId

Menghapus webhook mailbox.

AUTH: MAILBOX BEARER TOKEN

Event mail.received

Event ini dikirim setelah email berhasil tersimpan ke database.

Webhook Payload
{
  "event": "mail.received",
  "data": {
    "mailboxId": "uuid",
    "messageId": "uuid",
    "email": "mybot@bltzmail.biz.id",
    "from": "sender@example.com",
    "fromName": "Sender Name",
    "subject": "Verification Code",
    "text": "Your code is 123456",
    "html": "<p>Your code is 123456</p>",
    "receivedAt": "2026-08-28T00:00:00.000Z"
  }
}

Webhook Signature

Setiap request webhook memiliki signature HMAC SHA-256 menggunakan secret webhook.

Header Isi
X-Eversa-Event Nama event, contoh mail.received.
X-Eversa-Signature sha256=<HMAC>
User-Agent BLTZMAIL/1.0
Node.js Signature Verification
const crypto = require('crypto')

function verifySignature(rawBody, secret, signatureHeader) {
  const expected =
    'sha256=' +
    crypto
      .createHmac('sha256', secret)
      .update(rawBody)
      .digest('hex')

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  )
}
DELIVERY ENGINE

Delivery History & Retry

Setiap pengiriman webhook dicatat pada delivery log. BLTZMAIL juga memiliki retry worker untuk endpoint yang gagal.

GET /api/v1/mailboxes/:id/webhooks/:webhookId/deliveries

Mengambil riwayat delivery sebuah webhook. Parameter query limit dapat digunakan dengan nilai 1 sampai 100.

AUTH: MAILBOX BEARER TOKEN
pending Delivery baru dibuat dan belum diproses.
processing Sedang melakukan HTTP POST ke endpoint webhook.
delivered Endpoint memberikan response HTTP sukses.
failed Delivery gagal dan masih dapat dicoba ulang.
dead Delivery tidak akan dicoba ulang lagi.

Retry behavior

HTTP status 408, 429, dan 5xx dianggap retryable. Network error atau timeout juga dicatat sebagai failed.

HTTP Timeout 10 detik per delivery.
Retry Delay Delivery gagal dijadwalkan sekitar 1 menit kemudian.
Worker Interval Retry worker memeriksa queue setiap 30 detik.
Maximum Attempts Maksimal 5 attempt, kemudian status menjadi dead.
REFERENCE

HTTP Status & Error

200 Request berhasil.
201 Resource berhasil dibuat.
400 Input atau URL tidak valid.
401 Token/API authentication diperlukan atau tidak valid.
404 Mailbox, pesan, attachment, atau webhook tidak ditemukan.
409 Resource bentrok, sudah digunakan, duplicate, atau limit tercapai.
413 Email incoming melebihi batas ukuran yang diterima.
500 Terjadi kegagalan internal pada server.
503 Layanan atau autentikasi belum tersedia.
Error Format
{
  "success": false,
  "message": "Pesan tidak ditemukan."
}
EXAMPLE

Contoh Node.js

Contoh membuat mailbox, menyimpan access token, lalu mengambil pesan.

Node.js 18+
const API = 'https://bltzmail.biz.id/api/v1'
const API_KEY = 'YOUR_API_KEY'

async function main() {
  const createRes = await fetch(`${API}/mailboxes`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-bltzmail': API_KEY
    },
    body: JSON.stringify({
      username: 'mybot'
    })
  })

  const createData = await createRes.json()

  if (!createData.success) {
    throw new Error(createData.message)
  }

  const mailboxId =
    createData.data.mailboxId

  const accessToken =
    createData.data.accessToken

  console.log(
    'Email:',
    createData.data.email
  )

  const messagesRes = await fetch(
    `${API}/mailboxes/${mailboxId}/messages`,
    {
      headers: {
        Authorization:
          `Bearer ${accessToken}`
      }
    }
  )

  const messages =
    await messagesRes.json()

  console.log(messages)
}

main().catch(console.error)