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.

Satu-satunya kredensial dalam API ini adalah kunci akun Anda, yang dijelaskan di bawah — satu untuk akun gratis, lebih banyak di paket berbayar. Kunci tidak punya tingkatan sendiri: setiap panggilan dinilai berdasarkan paket yang dimiliki akunnya saat itu, sehingga kunci yang sama lepas dari batas gratis dan membuka kumpulan premium begitu Anda berlangganan, lalu kembali ke kuota gratis saat paket berakhir. Domain publik tidak memerlukan kunci; jika dikirim bersamanya, kunci menghitung panggilan Anda untuk akun Anda, bukan untuk alamat IP Anda. Kunci yang dikirim dan tidak dikenal atau sudah dicabut akan dijawab 401 dengan unauthorized pada endpoint mana pun, apa pun domainnya — sehingga salah ketik langsung terlihat alih-alih tersamar sebagai kotak masuk yang tampak kosong.

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 97 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 dari paket berbayar, permintaan yang sama menjawab 404 — persis sama dengan jawaban untuk domain yang tidak kami host, secara sengaja, agar kumpulan tidak bisa didaftar dengan menebak nama. Tidak pernah kotak masuk.

Di mana domain kumpulan berada

GET /api/v1/domains dengan kunci Anda mengembalikan domain publik dan nama-nama domain milik kumpulan itu. Panggilan yang sama tanpa kunci — atau dengan kunci dari akun gratis atau yang sudah kedaluwarsa — mengembalikan domain publik, berapa banyak domain yang dimiliki kumpulan itu dan berapa biayanya, tetapi tidak pernah sebuah nama: menjauhkannya dari daftar hitam surel sekali pakai itulah yang dibeli oleh paket ini. Pelanggan yang sudah masuk juga melihat kumpulan itu di pemilih domain pada beranda.

curl -s https://grabmail.io/api/v1/domains \
  -H "Authorization: Bearer gm_live_…"

{
  "public": ["grabmail.io", "mixozia.com", "linqmail.com"],
  "premium": {
    "count": 97,
    "unlocked": true,
    "domains": ["one-of-the-pool.com", "another-of-the-pool.com", "…"]
  }
}

Memeriksa kunci

GET /api/v1/me adalah satu-satunya panggilan yang menilai sebuah kunci dengan sendirinya: 200 berisi paket, periode saat ini, kuota yang terpakai dan tersisa, alamat yang dipegang, dan batas laju Anda — atau 401 unauthorized jika kuncinya tidak dikenal atau sudah dicabut. Panggil ini lebih dulu saat sesuatu di kumpulan menjawab 404: jawaban itu sengaja menyembunyikan masalah kunci, sedangkan yang ini menampakkannya.

curl -s https://grabmail.io/api/v1/me \
  -H "Authorization: Bearer gm_live_…"

{
  "plan": "premium",
  "status": "active",
  "premium": true,
  "period": { "start": "2026-09-14T00:00:00Z", "end": "2026-10-14T00:00:00Z" },
  "usage": { "messages": 12, "addresses": 5, "consumed": 12, "quota": 2000, "left": 1988, "over": false },
  "addresses_held": 5,
  "limits": { "requests_per_second": 2, "requests_per_minute": null, "requests_per_day": null, "api_keys": 1, "address_cap": null },
  "pool": { "count": 97, "access": true, "domains": "GET https://grabmail.io/api/v1/domains" }
}

Apa yang dijawab kumpulan

Setiap kasus, beserta alasannya. Dua yang pertama tampak mengejutkan sampai alasannya dibaca.

404

unknown_domain — tanpa kunci, atau kunci dari akun gratis atau yang sudah kedaluwarsa. Sama persis dengan jawaban untuk domain yang tidak kami host, secara sengaja: membedakan keduanya akan membuat kumpulan bisa didaftar dengan menebak nama. Periksa kuncinya dengan /api/v1/me.

401

unauthorized — kunci yang dikirim tidak dikenal atau sudah dicabut. Dijawab di endpoint mana pun, apa pun domainnya: ini menyatakan sesuatu tentang kuncinya, bukan tentang sebuah domain.

402

quota_reached — kuota periode ini sudah habis dan fitur melewati kuota sedang mati. overage_cap / overage_funds — fitur melewati kuota sedang aktif, tetapi batas yang Anda tetapkan sudah tercapai atau saldo tidak mencukupi. Alamat yang sudah dipegang tetap berfungsi dalam ketiga kasus ini.

403

address_taken — pelanggan lain sedang memegang alamat itu. Pilih nama lain.

409

address_limit — dicadangkan untuk paket yang membatasi jumlah alamat. Belum ada paket yang melakukannya hari ini.

429

rate_limited — di paket gratis (tanpa kunci, atau dengan kunci gratis), lebih dari 60 permintaan per menit, atau lebih dari satu pembacaan per detik pada satu alamat; dengan kunci berbayar, lebih dari 2, 3, atau 5 pembacaan per detik pada satu alamat. daily_limit_reached — 1.000 permintaan gratis hari ini sudah habis terpakai. Paket berbayar tidak punya batas per menit maupun batas harian. Keduanya menyertakan Retry-After.

Alamat yang dipegang dan kuota

Sebuah alamat premium dipegang oleh akun pertama yang membacanya dengan kunci yang sah — pembacaan apa pun, di endpoint mana pun atau lewat MCP, tidak ada yang perlu dicadangkan lebih dulu. Selama dipegang, hanya akun itu yang bisa membacanya; siapa pun yang lain mendapat 403. Alamat itu tetap dipegang sampai Anda melepaskannya dari dasbor, atau paketnya berakhir — pada tanggal berakhirnya, tanpa masa tenggang.

Kuota menghitung unit: sebuah pesan yang diterima di alamat premium atau sebuah alamat premium baru yang dibuka, mana pun yang lebih dulu terjadi — jadi alamat yang Anda buka dan tidak pernah dibaca tetap memakai satu unit. Membaca ulang alamat yang sudah dipegang itu gratis. Tidak ada paket yang membatasi berapa banyak alamat yang dipegang sebuah akun; kuota itulah yang membatasinya, dan /api/v1/me menunjukkan berapa sisanya.

Alias, juga pada alamat premium

Setiap daftar kotak masuk membawa sebuah alias: alamat kedua yang mengantar ke kotak masuk yang sama dan tidak mengungkap apa pun tentangnya. Berikan alias itu ke sebuah formulir dan poll alamatnya; siapa pun yang memegang alias itu akan melihat kotak masuk kosong, selalu. Alias ini tetap sama untuk alamat tertentu, gratis, dan dikembalikan untuk alamat premium persis seperti untuk alamat publik. Domainnya adalah salah satu milik kami dan sengaja tidak dicantumkan di mana pun.

Semuanya, dalam empat panggilan

KEY="gm_live_…"   # dari halaman kunci API Anda, dengan paket berbayar
# 1. Periksa kunci: paket, sisa kuota, batas laju. 401 jika salah.
curl -s https://grabmail.io/api/v1/me -H "Authorization: Bearer $KEY"

# 2. Daftar kumpulan. Nama-namanya hanya ada di jawaban jika memakai kunci berbayar.
curl -s https://grabmail.io/api/v1/domains -H "Authorization: Bearer $KEY"

# 3. Baca kotak masuk pada salah satunya. Pembacaan pertama ini memegang alamatnya dan menghitung satu unit.
curl -sG https://grabmail.io/api/v1/mailbox -H "Authorization: Bearer $KEY" \
  --data-urlencode "address=a7f3k2@one-of-the-pool.com"

# 4. Baca satu pesan, header yang sama.
curl -sG https://grabmail.io/api/v1/message/MESSAGE_ID -H "Authorization: Bearer $KEY" \
  --data-urlencode "mailbox=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 kumpulan premium dan tidak ada yang lain. 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",
  "alias": "hq8kd2m4p7zt@alias-domain.example",
  "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, bad_cursor, unknown_domain, not_found, rate_limited, daily_limit_reached, unauthorized, dan, khusus di kumpulan premium, quota_reached, overage_cap, overage_funds, address_taken, dan address_limit.

Sebagian error membawa lebih dari dua kolom itu: sebuah hint yang menyebutkan apa yang harus dilakukan, sebuah tautan docs, pada 404 dan 429 sebuah blok premium_pool berisi harga kumpulan dan cara membukanya, serta pada 429 akibat batas gratis sebuah blok upgrade yang menjelaskan batas apa saja yang hilang dengan paket berbayar — ditulis untuk asisten yang membaca isi respons atas nama seseorang, sehingga ia bisa meneruskan pilihan itu alih-alih menyerah.

Batas laju

Gratis, tanpa kunci: 60 permintaan per menit dan 1.000 per hari, per alamat IP. Setiap panggilan ke sebuah kotak masuk ikut dihitung — menampilkan daftar isinya, membaca pesan, badan HTML pesan, lampiran, penghapusan — begitu juga setiap panggilan alat MCP. Hitungan harian disetel ulang pukul 00:00 UTC.

Dengan kunci API gratis, kuota yang sama mengikuti akun Anda, bukan alamat IP Anda — berguna saat panggilan Anda datang dari alamat yang berubah-ubah, seperti runner CI. Akun gratis punya satu kunci, dan kotak masuk yang dibacanya tercantum di kotak masuk Anda. Buat kunci gratis

Di dalam jatah itu, satu pembacaan per detik per alamat: melakukan polling kotak masuk sekali per detik adalah irama yang dimaksudkan.

Paket berbayar bebas dari batas per menit dan batas harian. Kirim kunci paket berbayar sebagai Authorization: Bearer, dan yang tersisa hanyalah batas per alamat dari paket Anda — 2, 3, atau 5 permintaan per detik, di semua domain, dihitung per akun. Premium mulai dari $12,99 per bulan. Lihat paketnya

Kotak masuk di situs ini tidak memakai jatah API gratis: halaman yang dibiarkan terbuka akan terus memeriksa surat masuk selama Anda membutuhkannya.

Melewati batas, Anda akan mendapat 429 dengan header Retry-After dalam detik bulat: rate_limited untuk batas per menit atau per alamat, daily_limit_reached untuk batas harian, disertai sisa waktu hingga tengah malam UTC. Setiap respons atas permintaan gratis menunjukkan sisa jatah Anda: X-RateLimit-Remaining untuk menit berjalan, X-RateLimit-Daily-Remaining untuk hari berjalan.

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 →