Authentication
Base URL, bearer credentials, scope rules, and error conventions for the OpenEmail HTTP API.
Every OpenEmail operation is an HTTP call against a single base URL. The CLI and the interactive console are clients of this API — anything they do, you can do directly.
This page covers what every request needs, whichever endpoint it calls. For a specific endpoint, see the API reference in its own tab above — it is generated from the spec and covers the whole surface.
Base URL
https://api.open.emailEvery path is versioned and already includes the prefix, so a full request URL
looks like https://api.open.email/api/v1/identities. Examples below assume:
export API="https://api.open.email/api/v1"JMAP is advertised on its own hostname, jmap.open.email, and is not part of
this REST contract.
Authentication
Every request carries a bearer credential:
curl "$API/auth/whoami" -H "Authorization: Bearer $TOKEN"There are two kinds, and which one you hold determines what you can reach:
| Credential | Prefix | Scope |
|---|---|---|
| API key | oek_ | The account, and every mailbox under it; or, limited to some domains, only those |
| Mailbox app password | oemp_ | One mailbox |
A request with no credential is refused with 401 unauthorized. A mailbox app
password used on an account-level route is refused with 403 insufficient_scope — it is a valid credential, just not for that route. An API
key limited to some domains reaches only those domains and the mailboxes with an
address on them: account-level routes refuse it with 403 account_credentials_required, and another domain's resources answer 404.
Four routes need no credential at all: the health check, calendar feed and webhook fetch URLs (where the token in the path is the credential), and the public branding reads a sign-in screen needs before anyone has signed in.
Check a credential
Describes the credential you are holding — useful when a call returns 403 and
you need to know what you actually authenticated as:
{
"type": "mailbox",
"accountId": "acct_...",
"mailboxId": "mb_...",
"credentialId": "cred_...",
"keyId": null
}type is account, mailbox, or system. The other fields are populated
according to that type — a mailbox credential names its mailbox, an account key
does not.
Find your mailbox's id
A mailbox app password's own mailbox is the mailboxId that whoami answers, and
that id is what every {mailboxId} path segment takes:
curl "$API/mailboxes/$MAILBOX_ID/messages" -H "Authorization: Bearer $TOKEN"There is no alias for it: a path with me in place of the id answers 404.
Errors
Errors always answer with a machine-readable code:
{ "error": "address_taken" }Schema failures carry the offending fields alongside the code:
{ "error": "validation_failed", "issues": [] }Codes are snake_case and stable — match on error, not on the HTTP status or
any human-readable text, both of which are shared across several conditions.
In the TypeScript SDK
The TypeScript SDK sends the credential for you, to
the API's address only, and reads OPENEMAIL_API_KEY when you give it none
(The client).
auth.whoami is GET /auth/whoami, and
a failed call rejects with one error type whose code is the API's error
(Errors and retries).
Where to go next
These guides walk the flows most people need first:
- Mailboxes — create, list, and read mailboxes.
- Messages — list a mailbox and read a message back.
- Sending — send from a mailbox, per-recipient results.
For anything else, the API reference covers every endpoint with its schemas and a runnable example per language.