Referensi API

Ikhtisar

Kotak masuk tidak pernah dibuat — ia ada begitu sebuah pesan tiba di suatu alamat, dan hilang 5 hari kemudian. Tidak ada yang perlu didaftarkan, jadi pada domain publik API tidak mengenal konsep pengguna, proyek, atau token.

• Setiap respons berupa JSON, termasuk setiap error.
• Semua waktu dalam UTC dengan format RFC 3339 — 2026-08-04T18:31:07Z.
• Id pesan adalah string opak. Jangan diurai.
• Hanya terima. Tidak ada endpoint untuk mengirim email, memang disengaja.

URL dasar

Hanya HTTPS; HTTP biasa akan dialihkan. Versi berada di path, dan v1 tidak akan berubah bentuk di bawah Anda — perubahan yang tidak kompatibel akan mendapat nomor baru.

Autentikasi: Tidak Diperlukan

Tidak ada di domain publik. Siapa pun yang mengetahui suatu alamat dapat membaca kotak masuknya, melalui API sama seperti melalui situs web. Itulah konsekuensi dari layanan email sekali pakai bersama, jadi jangan pernah gunakan hal yang penting bagi Anda di alamat publik.

Domain yang Anda arahkan ke sini akan dijawab lewat endpoint yang sama, tanpa kunci juga. Arahkan MX-nya ke kami dan pesan pertama akan menghubungkannya; lihat menghubungkan domain. Kotak masuk di dalamnya dapat dibaca oleh siapa pun yang mengetahui alamatnya, persis seperti domain publik.

Ada satu kasus yang masih memakai header: domain yang kami tutup atas permintaan dibaca dengan Authorization: Bearer <key>, dan kunci yang salah atau hilang akan dijawab dengan 401 dan unauthorized. Kunci dibandingkan dalam waktu konstan, sehingga kunci yang salah membutuhkan waktu penolakan yang sama dengan waktu penerimaan kunci yang benar.

Domain premium

Satu-satunya pengecualian dari aturan di atas. Domain publik ada di daftar blokir surel sekali pakai, dan karena itu formulir pendaftaran kadang menolak alamat di domain tersebut. Paket berbayar membuka pool berisi 92 domain .com privat, yang dijauhkan dari daftar itu.

Tidak ada yang berubah di API. Jalur, parameter, dan bentuk respons yang sama. Satu-satunya perbedaan adalah satu header: alamat premium dibaca dengan Authorization: Bearer gm_live_…, memakai kunci dari kunci API Anda. Tanpa kunci yang sah, permintaan yang sama menjawab 402 atau 403 — bukan kotak masuk.

# A public domain: no header at all.
curl -sG https://grabmail.io/api/v1/mailbox \
  --data-urlencode "address=a7f3k2@grabmail.io"

# A premium domain: the same call, plus a key.
curl -sG https://grabmail.io/api/v1/mailbox \
  -H "Authorization: Bearer gm_live_…" \
  --data-urlencode "address=a7f3k2@one-of-the-pool.com"

Domain publik dan domain milik Anda tetap gratis, tanpa kunci dan tanpa batas di semua paket, termasuk yang gratis. Kuota hanya menghitung pesan yang masuk ke pool premium. Paket dan harga ada di halaman paket.

Endpoint

$ curl -G https://grabmail.io/api/v1/mailbox \
  --data-urlencode "address=k7fq2m@grabmail.io"

{
  "address": "k7fq2m@grabmail.io",
  "count": 1,
  "next": null,
  "messages": [
    {
      "id": "01JR8W2K4Q",
      "from": "no-reply@example.com",
      "subject": "Your verification code",
      "date": "2026-08-04T18:31:07Z",
      "seen": false,
      "attachments": 0,
      "expires_at": "2026-08-09T18:31:07Z"
    }
  ]
}

$ curl -G https://grabmail.io/api/v1/message/01JR8W2K4Q \
  --data-urlencode "mailbox=k7fq2m@grabmail.io"

{
  "id": "01JR8W2K4Q",
  "from": "no-reply@example.com",
  "to": "k7fq2m@grabmail.io",
  "subject": "Your verification code",
  "date": "2026-08-04T18:31:07Z",
  "text": "Your code is 481920. It expires in 10 minutes.",
  "html": null,
  "attachments": []
}

$ curl -X DELETE -G https://grabmail.io/api/v1/message/01JR8W2K4Q \
  --data-urlencode "mailbox=k7fq2m@grabmail.io"

{
  "deleted": true,
  "id": "01JR8W2K4Q"
}

Lampiran

Setiap pesan mencantumkan lampirannya dengan URL yang sudah siap pakai. Ambil dengan otorisasi yang sama seperti pesan itu sendiri.

GET /api/v1/attachment/{id}?mailbox={address}

Selalu menjawab dengan application/octet-stream beserta Content-Disposition: attachment, apa pun label yang diberikan pengirim. Itu disengaja: mengembalikan text/html milik orang asing akan memungkinkan lampiran berjalan sebagai halaman di origin ini. Tipe sebenarnya ada di JSON pesan, di mana ia berupa data, bukan instruksi.

Error

Setiap kegagalan berupa JSON dengan dua field yang sama, sehingga klien menanganinya di satu tempat. Status membawa kategorinya, error adalah slug yang stabil dan dapat dibaca mesin, dan message ditujukan untuk manusia dan dapat diubah kata-katanya kapan saja.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error":   "invalid_address",
  "message": "address must look like name@domain"
}

Jangan pernah membuat percabangan berdasarkan message. Slug yang digunakan adalah invalid_address, unknown_domain, not_found, dan rate_limited.

Batas laju

Satu permintaan per detik, per alamat. Melakukan polling kotak masuk sekali per detik adalah pola yang dimaksudkan dan tidak pernah dibatasi.

Melebihi batas, Anda akan mendapat 429 dengan Retry-After dalam detik. Tidak ada kuota harian dan tidak ada kredit burst yang perlu dikelola.

Retensi

Sebuah pesan dihapus 5 hari setelah tiba, baik sudah dibaca maupun belum. Setiap pesan membawa expires_at, jadi Anda tidak perlu menghitung tanggal itu sendiri.

Ini batas keras, bukan pengaturan — tidak ada parameter yang memperpanjangnya. Jika sebuah pesan harus bertahan lebih lama dari jendela waktu ini, ambil dan simpan di sisi Anda.

Domain Anda sendiri

Arahkan MX Anda ke smtp.grabmail.io dan setiap alamat di domain Anda akan dijawab melalui endpoint yang sama ini — tidak ada API kedua yang perlu dipelajari, tidak ada pendaftaran, dan tidak ada kunci.

Hubungkan domain →