# ansible.to — email for AI agents
> No login, no SMTP, just an API call. Pick any @ansible.to address, get a trial inbox, and start sending/receiving email programmatically. Usage-based, no subscriptions.

## Quickstart
- [OpenAPI specification](https://ansible.to/openapi.yaml): Full API reference with schemas
- [Landing page](https://ansible.to): Live session API key and curl example

## How it works

### Authentication
Pass your API key via the `Authorization` header:

```
Authorization: Bearer <api_key>
```

When you visit [ansible.to](https://ansible.to), the page gives you a real, pre-generated API key (format: `key_<base58>`) ready to use. Send your first email to activate the trial — this same key works permanently.

### Core endpoints

`GET /v1/account` — Account state (email, credits, trial status).
`DELETE /v1/account` — Close account and delete all data. Irreversible.

`POST /v1/send` — Send an email.
- `from`: local-part of `@ansible.to` (e.g. `my-agent` → `my-agent@ansible.to`)
- `to`, `subject`, `text`, `html`, `cc`, `bcc`, `reply_to`, `attachments`
- First send creates the account (trial, 10 credits). Returns `{ id, credits }`.
- Subsequent sends debit 1 credit per email.
- Trial accounts can only send to their verified email.

`GET /v1/inbox` — List received messages (newest first).
- Query params: `unread` (boolean), `n` (1-100, default 20)

`GET /v1/inbox/{id}` — Read a full message. Marks as read.
- Returns `{ id, from, to, subject, text, html, ts, is_read }`

`POST /v1/inbox/{id}/reply` — Reply to a message (1 credit).
- Automatically sets threading headers (In-Reply-To, References, Re:).
- Body: `{ text, html? }`

### Errors
| Status | Meaning |
| --- | --- |
| 401 | Invalid API key |
| 402 | Insufficient credits |
| 403 | Trial account restriction |
| 409 | Route name taken |
| 429 | Rate limited (3/hr to one address) |

### Limits
- Subject: 998 characters max
- Text body: 50KB max
- HTML body: 100KB max
- Trial: 24h lockout, 1 route, outbound only to verified email
- Rate limit: 3 sends per hour to the same recipient address

### Pricing
- First 10 credits free (trial)
- Top up: $10 for 10,000 credits (unlocks full send/receive)
- No monthly subscription — pay as you go