# Overview

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](/docs/sdks/typescript): 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](/docs/quickstart) for a real mailbox in a
few minutes, or the [guides](/docs/guides/authentication) 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_`):

```bash
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](/docs/guides/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:

```json
{ "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:

```json
{ "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.

| Group | What it covers |
| --- | --- |
| **[Accounts](/docs/api/accounts)** | The tenant: lifecycle, usage and traffic statistics, allowance meters, and the audit trail. |
| **[Credentials](/docs/api/credentials)** | Who may call: account API keys, per-mailbox app passwords, WebAuthn security keys, password and recovery flows, and `whoami`. |
| **[Domains](/docs/api/domains)** | A 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. |
| **[Mailboxes](/docs/api/mailboxes)** | The mailbox resources themselves: create, list, delete and restore identities, settings and preferences, sharing grants, send-rate meters, and the mailbox-scoped event webhook. |
| **[Routing](/docs/api/routing)** | What 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. |
| **[Filtering](/docs/api/filtering)** | What 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. |
| **[Labels](/docs/api/labels)** | Folders and labels: create, rename, delete, per-label statistics, and the IMAP-shaped UID and vanished feeds a mail client syncs from. |
| **[Pickups](/docs/api/pickups)** | POP3 pickup sources, for pulling mail in from another provider. |
| **[Messages](/docs/api/messages)** | The 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. |
| **[Threads](/docs/api/threads)** | Conversations, grouped for you. |
| **[Uploads](/docs/api/uploads)** | Staging attachment bytes once, then referencing them from a send, compose, or reply. |
| **[Delivery](/docs/api/delivery)** | Sending: send, reply, schedule, cancel, per-recipient delivery status, and a recipient's deliverability pre-flight. |
| **[Suppressions](/docs/api/suppressions)** | The do-not-send list; lift your own hard-bounce entries. |
| **[Push](/docs/api/push)** | Web Push device registrations: register an endpoint, complete the verification handshake, and receive content-free wakes whose tokens feed the changes endpoints. |
| **[PIM](/docs/api/pim)** | Calendars and address books, with sharing, subscriptions, invitations, and feeds. |
| **[Templates](/docs/api/templates)** | Stored, per-language messages the account sends by name with variables: create, write the copy, preview, send. |
| **[System](/docs/api/system)** | The 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](mailto:support@open.email).
