# kankan.email — Email inboxes for AI agents

> kankan.email gives any AI agent a real email inbox with zero signup.
> One API call creates a working address — FREE for 30 days, then $10/year
> (WeChat/Alipay ¥71 or 10 USDT TRC-20). 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://kankan.email
OpenAPI: https://kankan.email/openapi.json

## Quickstart

```bash
# 1. Create mailbox — active INSTANTLY, free for 30 days.
#    Response contains mail_key ONCE. Store it.
curl -X POST https://kankan.email/api/v1/mailboxes \
  -H 'content-type: application/json' \
  -d '{"name_hint":"openclaw"}'
# → {"address":"openclaw-x7k2@kankan.email","mail_key":"kk_...","status":"active","free_until":"..."}

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

# 2b. Send mail to ANY address (replies come back to your inbox)
curl -X POST https://kankan.email/api/v1/send -H 'content-type: application/json' \
  -d '{"from":"openclaw-x7k2@kankan.email","to":"someone@example.com","subject":"hi","text":"from my agent","key":"kk_..."}'

# 3. Renew before the free month ends — $10/year
curl -X POST https://kankan.email/api/v1/mailboxes/openclaw-x7k2@kankan.email/renew
# → {"order_no":"KK...","price":{"usd":10,"cny":71}, ...}
curl -X POST https://kankan.email/api/v1/pay -H 'content-type: application/json' \
  -d '{"order_no":"KK...","method":"usdt"}'     # → send 10 USDT TRC-20 to wallet
curl -X POST https://kankan.email/api/v1/pay -H 'content-type: application/json' \
  -d '{"order_no":"KK...","method":"xunhu"}'    # → open pay_url (WeChat/Alipay, ¥71)
curl https://kankan.email/api/v1/orders/KK...    # → {"status":"paid"} → expiry +1 year
```

## 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.
- Lost key = lost mailbox. Store it in your agent's config/secrets.

## Lifecycle & limits

- New mailboxes: active instantly, free for 30 days.
- Renewal: $10/year, extends expiry by 1 year from max(now, current expiry). Anyone can renew any mailbox (no key needed to pay).
- Expired mailboxes: mail stops arriving, reading blocked (403 MAILBOX_EXPIRED). Address reserved for a 30-day grace period — renew to restore; then released.
- Messages 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 via Cloudflare Email Routing; send via relay with your address as Reply-To (replies land in your inbox).
- Max 20 mailbox creations and 200 sends per IP/mailbox per day.

## Errors

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

## Endpoints summary

| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | /api/v1/mailboxes | none | create mailbox (free 30d, instant) |
| GET | /api/v1/mailboxes/{address} | none | public status + days_left |
| POST | /api/v1/mailboxes/{address}/renew | none | create renewal order |
| POST | /api/v1/pay | none | pay an order |
| GET | /api/v1/orders/{order_no} | none | order status (USDT auto-verified) |
| POST | /api/v1/send | mail_key | send email to any address |
| 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 |