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 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.

Pada domain milik Anda sendiri, kotak masuk bersifat privat, sehingga permintaan membawa kunci — yang membuktikan bahwa kotak masuk itu milik Anda. Kunci diterbitkan saat Anda verifikasi domain, ditampilkan sekali, dan hanya disimpan di sini sebagai hash:

Authorization: Bearer <your key>

Kunci yang salah atau hilang pada domain privat 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.

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, dan kotak masuknya hanya dapat dibaca dengan kunci Anda.

Hubungkan domain →