Skip to content
docs
Browse the docsAPI reference

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 URLhttps://api.dissolve.email
Versioned surface/v1/..., also served under /api/v1/... for SDKs and CLIs built for destroy.network
AuthenticationAuthorization: Bearer <token> with an sk_live_ API key or a dna_at_ OAuth token (Authentication)
BodiesJSON with Content-Type: application/json, except the OAuth token and revoke endpoints, which take form fields
AnswersJSON, except attachment downloads
Errors{ "error": { "code", "message", "details"? } } (Errors)
Request idEvery 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

SectionWhat it coversEndpoints
AccountThe credential, the account and the receiving domains.3
InboxesDisposable inboxes: create, read, extend, forward, delete.6
AliasesMore addresses that deliver into one inbox.3
MessagesMail in an inbox and its attachments.4
WaitingLong-polls that answer when mail or a verification code arrives.2
LabelsNamed colours on messages.6
IdentitiesAgent identities: an inbox, a password and an optional persona for one sign-up.9
VaultSaved credentials, encrypted at rest.5
WebhooksSigned HTTPS deliveries for new mail and inbox events.5
RulesForward, label or delete new mail by sender or subject.5
TemplatesSaved inbox settings.3
OAuthThe OAuth 2.1 authorization server (PKCE S256) and its discovery documents.6
CLIThe 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