Developer Reference v1 — PLANNED (backend in progress)

MailKayy API

Headless REST + WebSocket API for programmatic disposable mailbox management — QA signup flows, CI/CD verification pipelines, and webhook automation. This page is the living contract; endpoints activate as the Cloudflare Worker backend ships.

Base URL (planned): https://api.mailkayy.my.id/v1

Quick Start

bash — create an inbox, wait for mail, read it

# 1. Create a disposable mailbox (10 min TTL)
curl -X POST https://api.mailkayy.my.id/v1/mailboxes \
  -H "X-API-Key: sk_live_kay…" \
  -H "Content-Type: application/json" \
  -d '{"localPart": "qa-test-01", "domain": "mailkayy.my.id", "ttlMinutes": 10}'

# 2. Poll / subscribe for inbound messages (see WebSocket section)
curl https://api.mailkayy.my.id/v1/inbox \
  -H "X-API-Key: sk_live_kay…"

# 3. Fetch one message
curl https://api.mailkayy.my.id/v1/messages/msg-849201 \
  -H "X-API-Key: sk_live_kay…"

Authentication

All programmatic requests require an API key passed in the X-API-Key header. Keys are provisioned per-account from the admin console and can be revoked at any time. Never ship a key in client-side code.

header format

X-API-Key: sk_live_kay…

Browser-based access to the public website does not use API keys — it uses ephemeral session state instead. Admin console access uses a separate httpOnly session cookie.

Mailboxes

Messages

Domains

Live Stream (WebSocket)

Instead of polling, subscribe to the push channel. The website UI uses this internally — “Live Inbox Stream” updates you see are this socket in action.

javascript

const ws = new WebSocket("wss://api.mailkayy.my.id/v1/ws/inbox");

ws.onopen = () =>
  ws.send(JSON.stringify({ type: "subscribe", mailboxId: "mbx-…" }));

ws.onmessage = (e) => {
  const evt = JSON.parse(e.data);
  // evt.type: "message.new" | "mailbox.expiring" | "mailbox.purged"
  console.log(evt.type, evt.payload);
};

Rate Limits

120 req/min per API key (burst 30)
Admin login: 5 fails / 15 min per IP
Domain unlock: 3 attempts / hour

Responses include X-RateLimit-Remaining; exceed it and you get 429 + Retry-After.

Errors

200OK

400Malformed request body

401Missing/invalid API key or credentials

404Resource purged or never existed

429Rate limited — honor Retry-After

5xxRelay incident — retry with backoff

Status: Planned

The backend Worker is not deployed yet — this page documents the contract the frontend already speaks (see src/lib/api.ts). The web app currently runs on local mock data and needs no API key.