# dazou — temporary email API for AI agents

> Free disposable email inboxes on @dazou.top and @dazou.xyz. One GET request creates an address and returns a secret access token; use the token later to read messages (JSON or plain text), block until new mail arrives, and get verification codes and links already extracted. No signup, no API key, CORS enabled, every read endpoint works with plain GET.

Base URL: https://dazou.top
Web UI (humans): https://dazou.top/
OpenAPI spec: https://dazou.top/openapi.json

## Typical agent workflow (sign up somewhere and read the confirmation email)

1. Create an inbox:
   GET https://dazou.top/api/new
   -> 201 {"address":"swift-otter-482@dazou.xyz","token":"k7m2-x9qp-4hrt-wz3n-8cvb-j6fd","expires_at":"...", ...}
   Keep BOTH the address and the token. The token is the only key to the inbox and cannot be recovered.
2. Use the address (e.g. type it into a sign-up form).
3. Wait for the email (long-poll, returns as soon as a message arrives):
   GET https://dazou.top/api/inbox/{token}/wait?timeout=30
   -> {"timed_out":false,"messages":[{"subject":"Your code","code":"482913","codes":["482913"],"verification_links":["https://..."],"text":"...", ...}]}
   If "timed_out" is true, simply call /wait again.
4. Use "code" (best-guess one-time code) or "verification_links" from the message.

Shortcut for plain-text answers (fewer tokens): add ?format=text to any read endpoint, e.g.
   GET https://dazou.top/api/new?format=text
   GET https://dazou.top/api/inbox/{token}/wait?format=text

## Endpoints

### Create an inbox
GET or POST https://dazou.top/api/new
Optional parameters (query string, JSON body or form body):
- domain: "dazou.top", "dazou.xyz" (or "top"/"xyz"), or "random" (default: random)
- name: custom local part, 3-40 chars [a-z0-9._-] (default: random like "brave-falcon-271"). 409 address_taken if in use.
- ttl: lifetime in hours (default 168 = 7 days, max 720 = 30 days). Suffixes allowed: 90m, 12h, 3d.
Response 201:
{
  "address": "brave-falcon-271@dazou.top",
  "token": "k7m2-x9qp-4hrt-wz3n-8cvb-j6fd",
  "domain": "dazou.top",
  "created_at": "2026-01-01T12:00:00.000Z",
  "expires_at": "2026-01-08T12:00:00.000Z",
  "inbox_url": "https://dazou.top/api/inbox/k7m2-x9qp-4hrt-wz3n-8cvb-j6fd",
  "wait_url": "https://dazou.top/api/inbox/k7m2-x9qp-4hrt-wz3n-8cvb-j6fd/wait",
  "latest_url": "https://dazou.top/api/inbox/k7m2-x9qp-4hrt-wz3n-8cvb-j6fd/latest",
  "web_url": "https://dazou.top/#k7m2-x9qp-4hrt-wz3n-8cvb-j6fd"
}
Example: GET https://dazou.top/api/new?domain=dazou.top&name=my-bot-test&ttl=24

### Authentication
The token goes in the URL path: /api/inbox/{token}/...
Alternatives (same endpoints without the token segment): header "Authorization: Bearer {token}", header "X-Inbox-Token: {token}", or query "?token={token}".
Tokens are case-insensitive; dashes are optional.

### List messages
GET https://dazou.top/api/inbox/{token}
Optional: limit (default 50), since (ISO date or epoch ms: only newer messages), format=text
Response: {"address","domain","created_at","expires_at","count","messages":[{"id","received_at","from":{"address","name"},"subject","preview","code","codes","attachment_count","seen"}]}
Newest first. Listing does not mark messages as seen.

### Wait for new mail (long-poll)
GET https://dazou.top/api/inbox/{token}/wait
Optional: timeout seconds (default 30, max 60), since (ISO or epoch ms), html=0, format=text
- Without "since": returns all UNSEEN messages (oldest first) and marks them seen. So calling /wait repeatedly yields each new message exactly once.
- With "since": returns messages received after that time (use "next_since" from the previous response).
Response: {"address", ..., "timed_out": false, "next_since": "...", "messages":[<full message>, ...]}
If an email may already have arrived before you call /wait, it is still returned (it is unseen).

### Latest message
GET https://dazou.top/api/inbox/{token}/latest
Full content of the most recent message (marks it seen). 404 {"error":"no_messages"} if the inbox is empty.

### Read one message
GET https://dazou.top/api/inbox/{token}/messages/{id}
Optional: html=0 (omit HTML body), headers=1 (include all headers), format=text
Full message object:
{
  "id": "aB3dE5fG7hJ9kL",
  "received_at": "2026-01-01T12:01:00.000Z",
  "from": {"address": "no-reply@example.com", "name": "Example"},
  "to": "brave-falcon-271@dazou.top",
  "subject": "Your verification code",
  "code": "482913",                       // best guess one-time code, or null
  "codes": ["482913"],                    // candidates, most likely first
  "text": "Your code is 482913 ...",      // plain text (derived from HTML if needed)
  "html": "<html>...",                    // original HTML (omit with html=0)
  "links": ["https://..."],               // all http(s) links, in order
  "verification_links": ["https://example.com/verify?t=..."],  // links that look like confirm/verify/login/reset
  "attachments": [{"id","filename","mime_type","size","content_id","inline","available","url"}],
  "raw_url": "https://dazou.top/api/inbox/{token}/messages/{id}/raw",
  "attachment_count": 0,
  "seen": true,
  "sent_at": "Thu, 01 Jan 2026 12:00:59 +0000"
}

### Raw source and attachments
GET https://dazou.top/api/inbox/{token}/messages/{id}/raw  -> message/rfc822 (.eml), kept for messages up to 1 MB
GET https://dazou.top/api/inbox/{token}/messages/{id}/attachments/{attachment_id}  -> file (attachments up to 1 MB each are stored)

### Manage
DELETE https://dazou.top/api/inbox/{token}/messages/{id}  -> {"deleted":true}
DELETE https://dazou.top/api/inbox/{token}  -> deletes the inbox and all its messages; the address becomes free again
POST (or GET) https://dazou.top/api/inbox/{token}/extend?ttl=48  -> new expiry = now + ttl hours (max 720)
GET https://dazou.top/api/domains  -> available domains and limits

## Errors
JSON: {"error": "<code>", "message": "<human readable>"}
- 400 invalid_domain | invalid_name | invalid_ttl
- 401 missing_token | invalid_token (unknown, deleted or purged inbox)
- 404 not_found | message_not_found | no_messages | raw_not_available | attachment_not_found
- 409 address_taken
- 410 inbox_expired
- 429 rate_limited (about 20 inbox creations and 300 requests per minute per IP)

## Facts and limits
- Domains: dazou.top, dazou.xyz. Any address you did not create is rejected at SMTP time.
- Plus-addressing works: name+anything@domain is delivered to name@domain.
- Receive only: this service cannot send email.
- Max 200 messages per inbox (oldest dropped). Incoming emails up to 10 MB.
- Expired inboxes and their messages are permanently deleted (purge every 30 minutes).
- Inboxes are private to whoever holds the token, but this is a disposable service: do not use it for anything sensitive or long-lived (bank, main accounts, password recovery you care about).
- Reserved names (admin, postmaster, webmaster, hostmaster, abuse, security, support, ...) cannot be created.

## curl examples
curl -s "https://dazou.top/api/new?domain=dazou.top"
curl -s "https://dazou.top/api/inbox/$TOKEN/wait?timeout=45&format=text"
curl -s -H "Authorization: Bearer $TOKEN" "https://dazou.top/api/inbox/latest"
curl -s -X DELETE "https://dazou.top/api/inbox/$TOKEN"