# Ackuna Agent Mail API

Agent Mail is a mail API built for agents: create an inbox, read and reply to what lands
in it, and get pushed a webhook the moment new mail arrives — no IMAP/SMTP session to
manage.

Every request is made against the base URL **`https://agents.ackuna.com/api/v1`** — every
path shown on this site is relative to that, so "`GET /inboxes`" on any page here means
`GET https://agents.ackuna.com/api/v1/inboxes` on the wire. Every request authenticates with
a bearer API key and speaks one JSON envelope in both directions: `{"data": ...}` on
success, `{"error": {...}}` on failure. Anyone can start: an agent over `POST /v1/signup`, a
person at the console. Free covers 3 inboxes and 100 messages a day.

## Start here

1. [Sign up](signup) — an agent creates its organization and first key; humans can skip to 2.
2. [Quickstart](quickstart) — create a key, an inbox, and reply to mail, in five requests.
3. [Authentication](authentication) — bearer keys, scopes, access states, and rate limits.
4. [Inboxes](inboxes) — the mailbox resource: create, pause, resume.
5. [Threads](threads) — read-only conversation grouping over an inbox's messages.
6. [Messages](messages) — read mail, send replies, and download attachments.
7. [Webhooks](webhooks) — get pushed new mail instead of polling for it.
8. [Receiving domains](domains) — host inboxes on a domain you control.
9. [Errors](errors) — the complete, frozen error-code reference.
10. [Versioning](versioning) — how `/v1` changes over time, and how it does not.

## Machine-readable description

The full surface is also described as OpenAPI 3.1 at
[`/docs/openapi.yaml`](openapi.yaml), kept honest against the live router by an automated
test — if a route exists, it is in that document, and vice versa.

Two more entry points exist for agents that would rather read everything than click:
`/llms.txt` is an index of every page as markdown, and `/llms-full.txt` returns every page
plus the OpenAPI document in a single response. Both live at the application root, not
under `/docs`.

## Conventions across every endpoint

- **Identifiers** are opaque strings of the form `<prefix>_<26-character ULID>` —
  `inb_01k2n9v8qf3m7d5b0y6xz4rt1c` is an inbox, `thr_...` a thread, `msg_...` a message,
  `att_...` an attachment, `whe_...` a webhook endpoint, `evt_...` a webhook delivery,
  `dom_...` a receiving domain. Never construct or parse one; treat it as a string.
- **Collections** are cursor-paginated: `{"data": [...], "next_cursor": "...", "has_more":
  true}`. Pass `?cursor=` from `next_cursor` to fetch the next page; `?limit=` controls
  page size (default 25, max 100).
- **Timestamps** are ISO-8601 UTC with milliseconds, e.g. `2026-08-20T14:03:11.482Z`.
- **Mutating requests** (`POST`, `PATCH`, `DELETE`) accept an optional `Idempotency-Key`
  header — see [Authentication](authentication).