# kakan.email — Email inboxes for AI agents

> kakan.email gives any AI agent a real email inbox with zero signup.
> Create a mailbox with one API call, pay $1 (WeChat/Alipay ¥7.1 or 1.0 USDT TRC-20),
> then read email over REST using only the mailbox address and its mail_key.
> No accounts, no OAuth, no passwords. Receive-only. Messages kept 30 days.

Base URL: https://kakan.email
OpenAPI: https://kakan.email/openapi.json

## Quickstart (3 calls)

```bash
# 1. Create mailbox — response contains mail_key ONCE. Store it.
curl -X POST https://kakan.email/api/v1/mailboxes \
  -H 'content-type: application/json' \
  -d '{"name_hint":"openclaw"}'
# → {"address":"openclaw-x7k2@kakan.email","mail_key":"kk_...","order_no":"KK...","status":"pending_payment", ...}

# 2. Pay $1 (choose one)
curl -X POST https://kakan.email/api/v1/pay -H 'content-type: application/json' \
  -d '{"order_no":"KK...","method":"usdt"}'     # → send 1.0 USDT TRC-20 to wallet
curl -X POST https://kakan.email/api/v1/pay -H 'content-type: application/json' \
  -d '{"order_no":"KK...","method":"xunhu"}'    # → open pay_url (WeChat/Alipay, ¥7.1)

# Poll until active
curl https://kakan.email/api/v1/orders/KK...    # → {"status":"paid"}

# 3. Read mail (zero auth — address + key)
curl "https://kakan.email/api/v1/mailboxes/openclaw-x7k2@kakan.email/messages?key=kk_..."
curl "https://kakan.email/api/v1/mailboxes/openclaw-x7k2@kakan.email/messages/123?key=kk_..."
```

## Binding model

- `mail_key` (format `kk_` + 48 hex) is returned exactly once at creation; only its SHA-256 hash is stored.
- The key is the ONLY credential. Whoever holds it reads the mailbox.
- Key may be sent as `?key=` query param or `X-Mail-Key` header.
- If the key is lost before payment, just create a new mailbox. After payment there is no recovery — store it.

## Rules & limits

- Pending (unpaid) mailboxes are recycled after 24h; address is released.
- Messages are stored 30 days then auto-deleted.
- Max 20 mailbox creations per IP per day.
- Inbound mail capped at 512KB raw; text truncated 64KB, html 256KB.
- Receive-only: no sending, no SMTP access.

## Errors

JSON: `{"error":{"code":"...","message":"..."}}`
Codes: NOT_FOUND, BAD_KEY (401), NOT_ACTIVE (403, unpaid), RATE_LIMITED (429), BAD_METHOD (400).

## Endpoints summary

| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | /api/v1/mailboxes | none | create mailbox |
| GET | /api/v1/mailboxes/{address} | none | public status |
| POST | /api/v1/pay | none | start payment |
| GET | /api/v1/orders/{order_no} | none | order status (USDT auto-verified) |
| GET | /api/v1/mailboxes/{address}/messages | mail_key | list messages |
| GET | /api/v1/mailboxes/{address}/messages/{id} | mail_key | full message |
| DELETE | /api/v1/mailboxes/{address}/messages/{id} | mail_key | delete message |
| GET | /api/v1/stats | none | public counters |
| GET | /health | none | liveness |