Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer om_your_api_key_here

API keys are prefixed with om_ for production.

Getting an API key

Sign up at the Dashboard. You’ll receive a magic link to sign in.
Complete the setup wizard: configure your webhook URL, then copy your API key and base URL.
Use the API key in the Authorization header for all API requests.

See Quickstart for the full setup flow.

Key scopes

OpenMail has three kinds of API keys. All three authenticate the same way, as a Bearer token — they differ only in how much of your account they reach.

Key	Access
Account-wide	Everything. Can manage pods and inboxes, and mint or revoke scoped keys. This is the key you get at signup.
Pod-scoped	One pod — reading and sending from its inboxes, and creating more inboxes in it. Nothing in another pod. Cannot delete an inbox or change its webhook config, and no pod or key management.
Inbox-scoped	One inbox — reading and sending, nothing else. No other inbox, and no creating, modifying, or deleting inboxes.

Pick the narrowest scope that fits. A pod-scoped key suits a tenant that owns several inboxes; an inbox-scoped key suits a single agent that owns exactly one. Mint them with POST /v1/pods/{id}/api-keys and POST /v1/inboxes/{id}/api-keys respectively — both require an account-wide key, so a scoped key can never widen its own reach, and each pod or inbox can hold up to 20 active keys. See Pod-scoped API keys and Inbox-scoped API keys. The full token is returned once, at creation, and cannot be retrieved again — store it securely. Listing keys returns only a masked prefix and the last 4 characters.

Security

Keep your API key secret. Do not expose it in client-side code.
Prefer a scoped key when an integration only needs one pod’s inboxes, or one inbox. Revoke either any time with DELETE /v1/pods/{id}/api-keys/{keyId} or DELETE /v1/inboxes/{id}/api-keys/{keyId} — revocation is immediate.
Deleting an inbox revokes its inbox-scoped keys along with it.
If you believe your account-wide key has been compromised, contact support immediately for rotation.

Invalid authentication

// 401 Unauthorized
{
  "error": "unauthorized",
  "message": "Missing or invalid Authorization header"
}

Overview

Pods

Inboxes

Messages

Attachments

Getting an API key

Key scopes

Security

Invalid authentication

​Getting an API key

​Key scopes

​Security

​Invalid authentication

Getting an API key

Key scopes

Security

Invalid authentication