KAUNYMAILv2 / Documentation
Admin

Kauny Mail API

Buat alamat email instan di @kaunycatering.my.id, terima pesan secara realtime, dan ekstrak kode OTP lewat satu endpoint long-poll. Semua email masuk ditulis ke D1 dalam hitungan detik.

v2.0.0 REST / JSON X-API-Key long-poll ≤ 30s

01 Autentikasi

Kirim key lewat header X-API-Key (atau Authorization: Bearer). Key bot di bawah sudah punya scope read + write — cukup untuk semua operasi email, tidak bisa mengelola key atau pengaturan.

Base URLhttps://kauny-mail.maxluno47.workers.dev
API key botkmail_v2_80baa0f37c9e409e3433ea8eeaf9fcfa6ec21ce34416befb
HeaderX-API-Key: kmail_v2_80baa0f…
Domain email*@kaunycatering.my.idcatch-all otomatis
Catatan: key di halaman ini sengaja ditampilkan supaya bot bisa langsung pakai. Untuk key baru, scope berbeda, atau pencabutan, buat lewat /admin. Key disimpan sebagai SHA-256 di sisi server.

02 Quickstart

Dua langkah: buat inbox, lalu tunggu email masuk sambil minta kode diekstrak otomatis.

03 Endpoint

Semua respons JSON. Endpoint v1 lama (/api/inbox, /api/inboxes, /api/recent, /api/search) masih berfungsi.

POST/api/v2/inboxesBuat alamat email baru

Body JSON { "local": "user123" }. Kosongkan local untuk nama acak acc…. Karakter valid: huruf kecil, angka, titik, underscore, dash.

{"ok":true,"address":"user123@kaunycatering.my.id","created":true}
POST/api/v2/inboxes/batchBuat banyak inbox sekaligus

Body { "count": 50, "prefix": "twitter" }. count 1–100 (di-clamp), prefix opsional. Tanpa prefix, nama dibuat acak acc…; dengan prefix, hasilnya <prefix>-<acak>.

{"ok":true,
 "created":["twitter-1a2b3c4d@kaunycatering.my.id",
            "twitter-9f8e7d6c@kaunycatering.my.id", ...],
 "count":50}
GET/api/v2/grabOne-call farming: inbox baru + OTP sekaligus

Endpoint inti untuk farming akun. Satu panggilan melakukan semuanya: membuat inbox unik, menunggu email masuk (long-poll), mengekstrak kode, dan mengosongkan inbox bila diminta. Tanpa state, tanpa tiga panggilan terpisah.

ParameterKeterangan
wait0–30 detik menunggu email (bawaan 20)
senderfilter pengirim — hanya email dari alamat/brand itu yang dianggap. Berguna kalau situs mengirim email welcome sebelum kode
localprefiks alamat: local=A1 → a1-x7k9pz@…. Tanpa ini, nama acak farm…
consume1 = isi inbox dihapus setelah dibaca → aman dipakai ulang untuk akun berikutnya
{"ok":true,
 "address":"tw-3f9a2b@kaunycatering.my.id",
 "inbox":  "tw-3f9a2b@kaunycatering.my.id",
 "code":"703901",
 "subject":"Confirm your email",
 "from":"security@account.meta.com",
 "links":["https://…"],
 "text":"Confirmation code 703901 …",
 "received_at":"2026-11-18T03:14:20.081Z"}

ok:false berarti timeout tanpa email — field waited berisi detik yang tersia. Bot tinggal retry dengan alamat baru.

Siklus bot lengkap: panggil grab → pakai address di form daftar akun situs → kode OTP ada di code, magic link di links[0] → selesai. Ulangi untuk akun berikutnya. Satu baris HTTP per akun.

Izin minimal: scope read + write cukup — tidak perlu admin.

GET/api/v2/inboxBaca pesan / tunggu OTP
ParameterKeterangan
addresswajib — alamat lengkap di domain kauny
wait0–30 detik, menahan koneksi sampai pesan berikutnya masuk
code1 = tunggu sampai ada pesan dengan kode terdeteksi
limit1–200 pesan, bawaan 100
sinceISO timestamp — hanya pesan setelah waktu itu
{"ok":true,"inbox":"user123@kaunycatering.my.id","found":true,
 "messages":[{"id":"<…@mail>","from":"security@account.meta.com",
  "subject":"Confirm your email","code":"703901","links":[...],
  "received_at":"2026-11-18T03:14:20.081Z"}],
 "latest":{"code":"703901", ...}}
GET/api/v2/inboxesDaftar semua inbox

Mengembalikan alamat terdaftar maupun alias yang muncul karena menerima email (auto: true), lengkap dengan jumlah pesan.

GET/api/v2/recentAliran pesan terbaru

Query ?limit=40&since=ISO. Lintas semua alamat, diurutkan terbaru dulu.

GET/api/v2/searchCari pesan

Query ?q=token, opsional address=… dan limit=…. Mencari subjek, pengirim, isi, alamat, dan kode.

DELETE/api/v2/inbox?address=…Hapus inbox + isinya

Respons: {"ok":true,"inbox":"…","deleted":true,"messages_deleted":12}.

DELETE/api/v2/inbox/bulkHapus banyak inbox

Body {"addresses":["a@…","b@…"]}, maksimal 200 alamat per panggilan.

GET/api/v2/export?address=…Unduh JSON inbox

Menghasilkan file <local>-export.json berisi seluruh pesan alamat itu (maks 200).

GET/api/v2/statsStatistik layanan

Total inbox/pesan/kode, aktivitas 24 jam & 7 hari, top pengirim, dan deretan 14 hari terakhir.

04 Pola long-poll OTP

Worker menahan koneksi hingga wait detik dan mengecek D1 tiap 1,2 detik. Begitu pesan dengan kode masuk, respons langsung dikirim — jangan menunggu penuh 30 detik.

1 — buat inboxPOST /api/v2/inboxes { "local": "verify01" }
2 — pakai alamat itu di situs tujuanverify01@kaunycatering.my.id
3 — tunggu kodeGET /api/v2/inbox?address=…&wait=30&code=1
4 — bacadata.latest.code atau data.latest.links
Kalau situs mengirim magic link bukan kode angka, code akan null — ambil URL dari latest.links. Ekstraktor hanya menangkap angka 4–8 digit atau alfanumerik setelah kata code/otp/pin/kode.
Langkah 1–4 di atas bisa diringkas menjadi satu panggilan GET /api/v2/grab — lihat bagian farming di daftar endpoint.

05 Farming akun

Playbook lengkap men-farm daftar akun di situs mana pun memakai Kauny Mail sebagai penyedia email verifikasi.

Pola dasar — satu akun = satu panggilan

Skala besar

Stok alamatPOST /api/v2/inboxes/batch {"count":100,"prefix":"farm"}
Paralelbanyak grab serentak dengan key read/write terpisah
Throughputwrite 90/menit per key — pakai beberapa key bila perlu
Kebersihanconsume=1 → inbox kosong lagi, siap dipakai ulang
Monitoringkartu "Grab 24 jam" di /admin + audit action=grab

Tips praktis

Selalu pakai sender= kalau situs mengirim email lebih dari satu (welcome dulu, kode belakangan). Tanpa filter, grab bisa menangkap email yang salah.
Reuse inbox dengan local=NamaAkun + consume=1 — alamat deterministik per slot farm (slot01-x9k2@…), mudah ditelusuri di audit.
Bersihkan stok lama berkala: DELETE /api/v2/inbox/bulk {"addresses":[…]} atau purge harian dari panel.
Jaringan: *.workers.dev diblokir DNS beberapa ISP Indonesia (XL, dst.) — bot di mesin rumah perlu DNS-over-HTTPS (browser: Secure DNS) atau VPN. Di VPS biasanya langsung tembus.

06 Webhook

Atur URL dan secret lewat /admin → Pengaturan. Tiap pesan masuk dikirim POST dengan tanda tangan HMAC-SHA256 di header X-Kauny-Signature (hex dari body persis).

{
  "event": "message",
  "service": "kauny-mail",
  "version": "2.0.0",
  "at": "2026-11-18T03:14:20.081Z",
  "data": {
    "id": "<message-id@host>",
    "to": "user123@kaunycatering.my.id",
    "from": "security@account.meta.com",
    "subject": "Confirm your email",
    "code": "703901",
    "links": ["https://…"],
    "received_at": "2026-11-18T03:14:20.081Z"
  }
}
Pengiriman best-effort: webhook gagal tidak membatalkan penyimpanan email. Status pengiriman tercatat di audit log. Ping test tersedia di POST /api/v2/settings/test-webhook.

07 Error & batas

StatusArtinya
400Alamat bukan @kaunycatering.my.id atau parameter tidak valid
401Key hilang, salah, atau sudah dicabut
403Scope kurang — misal key read dipakai untuk menulis
404Rute tidak ada
429Rate limit terlampaui: 600 read / 90 write / 120 admin per menit per key
500Gangguan internal; detail ada di field detail
Ukuran email maksimal8 MB — sisanya dipotong, email tetap tersimpan
Retensi pesan90 hari — bisa diubah di /admin
CORS* — bisa dipanggil langsung dari browser

08 Kompatibilitas v1

Endpoint lama masih aktif dan memakai key legasi dari environment. Rute-rutenya:

Buat inboxPOST /api/inbox
Baca pesanGET /api/inbox?address=…&wait=30&code=1
Daftar / aktivitas / cari/api/inboxes · /api/recent · /api/search
Health/api/health — publik
Disarankan pindah ke /api/v2/* dengan key kmail_v2_… supaya bisa dirotasi per aplikasi dan punya audit sendiri.