Reference
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.
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 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) |
| 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) |
| 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. Thesinceparameter 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 (
limitup 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 gonebefore it is swept away.
Sections
| Section | What it covers | Endpoints |
|---|---|---|
| Account | The credential, the account and the receiving domains. | 3 |
| Inboxes | Disposable inboxes: create, read, extend, forward, delete. | 6 |
| Aliases | More addresses that deliver into one inbox. | 3 |
| Messages | Mail in an inbox and its attachments. | 4 |
| Waiting | Long-polls that answer when mail or a verification code arrives. | 2 |
| Labels | Named colours on messages. | 6 |
| Identities | Agent identities: an inbox, a password and an optional persona for one sign-up. | 9 |
| Vault | Saved credentials, encrypted at rest. | 5 |
| Webhooks | Signed HTTPS deliveries for new mail and inbox events. | 5 |
| Rules | Forward, label or delete new mail by sender or subject. | 5 |
| Templates | Saved inbox settings. | 3 |
| OAuth | The OAuth 2.1 authorization server (PKCE S256) and its discovery documents. | 6 |
| CLI | The device flow the dna CLI signs in with. | 2 |
Rate limits and plans lists what each plan allows; Codes and waiting explains the long-poll endpoints in depth.
Something wrong or missing on this page? Tell us at support@dissolve.email.View as Markdown