# Caili Mail — mailboxes for agents

Receive-only email addresses at `@mail.caili.info`, for signing up to sites that only need an email and reading the verification code or link.
The API is compatible with mail.tm (same paths and fields), so mail.tm clients work if you change the base URL.

Base URL: `https://mail.caili.info`

## Quick start

1. Create a mailbox. Choose a username; if it is free you get it.

```
POST /accounts
Content-Type: application/json

{"address": "myname@mail.caili.info", "password": "a-strong-password"}
```

Shortcuts: send `{"username": "myname", "password": "..."}` instead of an address. Leave out `password` and one is generated and returned once in the response (`password` field). Leave out both and you get a random username.

- `201` → the account (`id`, `address`).
- `422` → name taken, invalid or reserved (`detail` says which). Pick another name.
- Names: 3–32 characters, `a-z 0-9 . _ -`, starting and ending with a letter or digit. A deleted name is never given out again.

2. Get a token.

```
POST /token
{"address": "myname@mail.caili.info", "password": "a-strong-password"}
→ {"token": "...", "id": "..."}
```

Send it as `Authorization: Bearer <token>` on every call below. Tokens last 90 days; get a new one any time with the password.

3. Use the address on the site, then wait for the email:

```
GET /messages/wait?timeout=60
```

Returns the newest unseen message as soon as it arrives (or immediately if one is already waiting) and marks it seen. `404` if nothing arrived within `timeout` seconds (max 120) — call it again. Add `markSeen=false` to leave it unseen.

The message includes:

- `codes` — numbers that look like verification codes, most likely first.
- `links` — links from the email, verification/confirm/login links first.
- `subject`, `from`, `text`, `html`.

## Other endpoints

| Method | Path | What |
|---|---|---|
| GET | /domains | Available domain (`mail.caili.info`) |
| GET | /me | Your account |
| GET | /messages?page=1 | Message list, newest first, 30 per page |
| GET | /messages/{id} | One message with text, html, codes, links, attachments |
| PATCH | /messages/{id} | `{"seen": true}` |
| DELETE | /messages/{id} | Delete a message |
| GET | /messages/{id}/download | Raw .eml |
| GET | /sources/{id} | Raw source as JSON |
| DELETE | /accounts/{id} | Delete your mailbox and all mail |

Lists return `{"hydra:member": [...], "hydra:totalItems": n}` like mail.tm; send `Accept: application/json` for a plain array.

## Good to know

- Receive only. You cannot send mail from these addresses.
- `name+anything@mail.caili.info` is delivered to `name`.
- Mail is kept. Each mailbox holds 40 MB; when full, the oldest mail is removed to make room.
- Keep the password: this mailbox is where the sites you sign up for send password resets.
- Anyone who knows the password can read the mail. Don't use it for accounts that matter to a person.
- Don't mass-register accounts on other sites. Limit: 30 new mailboxes per IP per hour.

## Example (curl)

```
curl -s -X POST https://mail.caili.info/accounts -H 'content-type: application/json' -d '{"username":"myname"}'
curl -s -X POST https://mail.caili.info/token -H 'content-type: application/json' -d '{"address":"myname@mail.caili.info","password":"PASSWORD_FROM_ABOVE"}'
curl -s 'https://mail.caili.info/messages/wait?timeout=90' -H 'authorization: Bearer TOKEN'
```
