# API reference

> Every public endpoint of the dissolve.email API, generated from the OpenAPI document apps/api builds from its own route definitions. Base URL, conventions and the sections.

Source: https://docs.dissolve.email/reference

The reference covers the scoped API at `/v1`, the OAuth server and the CLI's device flow: every operation with its scope, plan, parameters, body, code in four languages and an example answer.

## How it is made

The reference is generated from `openapi.json`, an OpenAPI 3.1 document the API builds from its own route definitions: the methods and paths come from the router, each operation's scope from the scope check in its route, and the words and examples from a description file a test holds to the routes. If a route is added or renamed without the document following, the API's tests fail. So every endpoint here exists, and every public endpoint is here.

Download the document at [/openapi.json](/openapi.json) to generate a client, import it into an HTTP tool or hand it to an agent.

## Basics

| | |
|---|---|
| Base URL | `https://api.dissolve.email` |
| Versioned surface | `/v1/...`, also served under `/api/v1/...` for SDKs and CLIs built for destroy.network |
| Authentication | `Authorization: Bearer <token>` with an `sk_live_` API key or a `dna_at_` OAuth token ([Authentication](/authentication)) |
| Bodies | JSON with `Content-Type: application/json`, except the OAuth token and revoke endpoints, which take form fields |
| Answers | JSON, except attachment downloads |
| Errors | `{ "error": { "code", "message", "details"? } }` ([Errors](/errors)) |
| Request id | Every answer carries `X-Request-Id`; quote it when you write to support |

## Conventions

- **Ids** are 21-character random strings, such as `V1StGXR8Z5jdHi6BmyT2k`. An inbox is named by its id in every path, never by its address.
- **Times** are ISO 8601 in UTC, such as `2026-11-19T10:30:00.000Z`. The `since` parameter of the wait endpoints takes the same form.
- **Field names** are camelCase in answers. Rule and template bodies take the snake_case names shown on their pages (`from_pattern`, `forward_to`), as the routes define them.
- **Lists are bounded, not paged.** There are no cursors: each list answers with everything that fits its bound. Inbox messages default to the newest 200 (`limit` up to 500), identity messages to the newest 50, and the other lists are small by plan limit (inboxes, rules, labels, webhooks, vault entries).
- **Scopes.** Each operation names the OAuth scope it needs; an API key has them all. Operations marked with a plan need at least that plan.
- **Expiry.** An inbox past its expiry answers `410 gone` before it is swept away.

## Sections

| Section | What it covers | Endpoints |
|---|---|---|
| [Account](/reference/account) | The credential, the account and the receiving domains. | 3 |
| [Inboxes](/reference/inboxes) | Disposable inboxes: create, read, extend, forward, delete. | 6 |
| [Aliases](/reference/aliases) | More addresses that deliver into one inbox. | 3 |
| [Messages](/reference/messages) | Mail in an inbox and its attachments. | 4 |
| [Waiting](/reference/waiting) | Long-polls that answer when mail or a verification code arrives. | 2 |
| [Labels](/reference/labels) | Named colours on messages. | 6 |
| [Identities](/reference/identities) | Agent identities: an inbox, a password and an optional persona for one sign-up. | 9 |
| [Vault](/reference/vault) | Saved credentials, encrypted at rest. | 5 |
| [Webhooks](/reference/webhooks) | Signed HTTPS deliveries for new mail and inbox events. | 5 |
| [Rules](/reference/rules) | Forward, label or delete new mail by sender or subject. | 5 |
| [Templates](/reference/templates) | Saved inbox settings. | 3 |
| [OAuth](/reference/oauth) | The OAuth 2.1 authorization server (PKCE S256) and its discovery documents. | 6 |
| [CLI](/reference/cli) | The device flow the dna CLI signs in with. | 2 |

[Rate limits and plans](/rate-limits) lists what each plan allows; [Codes and waiting](/verification) explains the long-poll endpoints in depth.
