Skip to Content

The full OpenEmail API: base URL, credentials, shared conventions, and what lives in each of the endpoint groups.

Every OpenEmail operation is an API call generated from the same OpenAPI document the service is built against. Each page carries the request and response schemas, a runnable example in seven languages, and status codes the endpoint returns.

The CLI and the interactive console are clients of this API. Anything they do, you can do directly. From TypeScript, every operation is also a method of the TypeScript SDK: each page here names its method and shows the call among its examples, and each method's page links back.

New here? Start with the Quickstart for a real mailbox in a few minutes, or the guides to learn how common flows work. This reference assumes you already know which endpoint you want.

Requests

https://api.open.email

Paths include their own version prefix, so a full URL reads https://api.open.email/api/v1/identities. Every request carries a bearer credential, either an account API key (oek_) or a mailbox app password (oemp_):

curl "https://api.open.email/api/v1/auth/whoami" \
  -H "Authorization: Bearer $TOKEN"

Which one you hold determines what you can reach: an API key covers the account and every mailbox under it (or only the domains it is limited to), a mailbox app password covers exactly one mailbox. The latter are also used to access OpenEmail's native webmail. A mailbox app password's mailbox is the mailboxId whoami answers, the id its {mailboxId} paths take. See Authentication for scope rules, the four routes that need no credential at all, and how to tell what you authenticated as.

Shared conventions

These hold across the surface, so the individual pages below do not repeat them.

Errors answer with a stable machine-readable code:

{ "error": "address_taken" }

Match on error, never on the HTTP status or the human-readable text. Both are shared across several conditions. Schema failures add an issues array alongside the code.

Listings page with cursor and limit. The response carries nextCursor, which is absent (not null, not empty) on the last page:

{ "messages": [], "nextCursor": "..." }

Treat the cursor as opaque, and hold the rest of your query parameters constant while crawling. limit caps at 200 on most listings.

Long-running and partial work answers 202 when accepted for later, and 207 when a batch succeeded for some entries and failed for others. A 207 is not a failure, so read the per-entry results rather than the status.

The groups

Endpoints are grouped by tag, in the order you meet them: set up the account, program what happens to mail, then use the mailbox.

GroupWhat it covers
AccountsThe tenant: lifecycle, usage and traffic statistics, allowance meters, and the audit trail.
CredentialsWho may call: account API keys, per-mailbox app passwords, WebAuthn security keys, password and recovery flows, and whoami.
DomainsA customer domain and everything hanging off it: registration and DNS checks, branding and logo, vanity hostnames, DMARC report views, the domain-scoped event webhook, and per-domain statistics.
MailboxesThe mailbox resources themselves: create, list, delete and restore identities, settings and preferences, sharing grants, send-rate meters, and the mailbox-scoped event webhook.
RoutingWhat an address does when mail arrives: routes to a mailbox, webhook, remote forward or group, pattern routes, allow and block address lists, and the signed fetch link webhook payloads point back to.
FilteringWhat happens to mail as it arrives: filter rules and Sieve scripts, the out-of-office auto-reply, verified forwarding, and the recipient's public disable link.
LabelsFolders and labels: create, rename, delete, per-label statistics, and the IMAP-shaped UID and vanished feeds a mail client syncs from.
PickupsPOP3 pickup sources, for pulling mail in from another provider.
MessagesThe store: list and read messages (parsed content, raw MIME, individual parts), flag and label updates, batch operations, search, trash and restore, incremental sync, spam-filter training, and the live event feed.
ThreadsConversations, grouped for you.
UploadsStaging attachment bytes once, then referencing them from a send, compose, or reply.
DeliverySending: send, reply, schedule, cancel, per-recipient delivery status, and a recipient's deliverability pre-flight.
SuppressionsThe do-not-send list; lift your own hard-bounce entries.
PushWeb Push device registrations: register an endpoint, complete the verification handshake, and receive content-free wakes whose tokens feed the changes endpoints.
PIMCalendars and address books, with sharing, subscriptions, invitations, and feeds.
TemplatesStored, per-language messages the account sends by name with variables: create, write the copy, preview, send.
SystemThe service liveness check.

Reading a page

Each operation page puts the request builder on the right. Fill in the parameters and press Send to call the API for real, with your own credential, and see the actual response next to the documented one. The language tabs above it emit the same request as ready-to-paste code.

Something missing or wrong? Tell us at support@open.email.