Skip to Content

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.email

Every 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:

CredentialPrefixScope
API keyoek_The account, and every mailbox under it; or, limited to some domains, only those
Mailbox app passwordoemp_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

GET /auth/whoami

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.