Overview
Ada dua cara pakai: Mode Tamu tanpa daftar (alamat sementara),
dan Mode Akses dengan kode akses (tanpa batas, bisa permanen).
Semua endpoint ada di prefix /api.
| Mode | Prefix | Header | Batas harian |
|---|---|---|---|
| Tamu | /api | x-session-id | Ya |
| Akses | /api/owner | x-owner-key | Tidak |
| Kelola | /api/owner/admin | x-admin-token | Tidak |
Masuk / Akses
Mode Tamu β ambil session dulu, lalu kirim di header:
curl -s https://mail.zumawa.ai.id/api/session
# {"sessionId":"<uuid>","tier":"public"}
curl -s https://mail.zumawa.ai.id/api/inboxes \
-H "x-session-id: <uuid>"Penting: begitu alamat dipakai lewat session, alamat itu jadi permanen β tidak ikut dibersihkan otomatis.
Mode Akses β pakai kode akses (x-owner-key atau
Authorization: Bearer β¦):
curl -s https://mail.zumawa.ai.id/api/owner/me \
-H "x-owner-key: tk_owner_β¦"Mode Tamu
| Method | Path | Keterangan |
|---|---|---|
| GET | /api/config | Info domain & mode |
| GET | /api/session | Ambil session tamu |
| GET | /api/inboxes | Daftar alamat milik session |
| POST | /api/inboxes | Buat alamat {localPart?, domain?} |
| DELETE | /api/inboxes/:addr | Lepas dari session (pesan tetap) |
| GET | /api/inboxes/:addr/messages | Baca pesan (?q= opsional) |
| GET | /api/inboxes/:addr/messages/:id | Satu pesan + lampiran |
Mode Akses tanpa batas
| Method | Path | Keterangan |
|---|---|---|
| GET | /api/owner/me | Info akun + jumlah alamat |
| GET | /api/owner/inboxes | Semua alamat milik key |
| POST | /api/owner/inboxes | Buat {localPart?, domain?, locked?, count?} |
| GET | /api/owner/inboxes/:addr | Detail + jumlah pesan |
| POST | /api/owner/inboxes/:addr/lock | Kunci / buka {locked} |
| GET | /api/owner/inboxes/:addr/messages | Baca pesan (?q=) |
| GET | /api/owner/inboxes/:addr/messages/:id | Satu pesan + lampiran |
| PATCH | /api/owner/inboxes/:addr/messages/:id | Tandai {read:true} |
| DELETE | /api/owner/inboxes/:addr/messages/:id | Hapus satu pesan |
| DELETE | /api/owner/inboxes/:addr | Kosongkan pesan (?purge=1 = hapus alamatnya juga) |
| GET | /api/owner/usage | Pemakaian penyimpanan |
| POST | /api/owner/maintenance | Bersihkan sekarang {dryRun?, storageCap?} |
| DELETE | /api/owner/messages/old?days=30 | Hapus pesan lebih lama dari N hari |
Penyimpanan
Aturan penyimpanan otomatis:
| Jenis alamat | Perilaku |
|---|---|
| Tanpa session | Pesan dibersihkan otomatis (maks 1 hari / 5 pesan). Alamat kosong ikut dibuang setelah 6 jam. |
| Dipakai lewat session | Permanen. Tidak pernah dibersihkan otomatis. |
| Kode akses (owner) | Permanen. Tidak pernah dibersihkan otomatis. |
| Ditandai kekal (pinned) | Permanen. Kebal dari semua pembersihan. |
Bisa diatur per alamat:
GET /api/owner/inboxes/:addr/retention
POST /api/owner/inboxes/:addr/retention
{ "mode": "forever" } // simpan selamanya
{ "mode": "keep_days", "days": 7 } // hapus lebih tua dari N hari
{ "mode": "keep_count", "count": 50 } // simpan N pesan terbaru
{ "mode": "forever", "pinned": true } // kebal semua pembersihanKelola Akses
# bikin kode akses (kode cuma tampil SEKALI)
curl -X POST https://mail.zumawa.ai.id/api/owner/admin/accounts \
-H "x-admin-token: <ADMIN_TOKEN>" \
-H "Content-Type: application/json" \
-d '{"label":"reza"}'
# daftar kode akses
curl https://mail.zumawa.ai.id/api/owner/admin/accounts \
-H "x-admin-token: <ADMIN_TOKEN>"
# cabut kode akses
curl -X DELETE https://mail.zumawa.ai.id/api/owner/admin/accounts/<id> \
-H "x-admin-token: <ADMIN_TOKEN>"
# riwayat aktivitas
curl https://mail.zumawa.ai.id/api/owner/admin/audit \
-H "x-admin-token: <ADMIN_TOKEN>"Error
Mode tamu dibatasi 10 alamat/jam, 50 alamat/hari, dan 60 permintaan/menit. Mode akses tanpa batas.
HTTP 429
{ "error": "Batas harian tercapai.", "retryAfter": 3599 }| Status | Arti |
|---|---|
400 | Data tidak lengkap / nama alamat tidak valid |
401 | Kode akses salah |
403 | Alamat bukan milik Anda |
409 | Alamat sudah dipakai orang lain |
429 | Batas harian tercapai |
Contoh Python
import re, time, requests
H = "https://mail.zumawa.ai.id"
KEY = "tk_owner_β¦"
o = {"x-owner-key": KEY, "User-Agent": "Mozilla/5.0"}
# bikin alamat permanen
r = requests.post(f"{H}/api/owner/inboxes", headers=o,
json={"localPart": "github", "locked": True})
print(r.json())
# tunggu kode OTP
addr = "github@zumawa.ai.id"
for _ in range(40):
msgs = requests.get(f"{H}/api/owner/inboxes/{addr}/messages",
headers=o).json()
if msgs:
m = re.search(r"\b\d{4,8}\b", msgs[0]["body"])
print("KODE:", m.group() if m else msgs[0]["body"])
break
time.sleep(3)Client siap pakai: zumawa_api.py di root repo.