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, inboxes, and custom domains, and mint or revoke scoped keys. This is the key you get at signup.
Pod-scoped	One pod — reading and sending from its inboxes, creating more inboxes in it, and adding a custom domain scoped to 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.

Neither scoped kind can touch sender rules: every /v1/policy call from a scoped key returns 403, reads included. An agent cannot read or change the policy that applies to it. 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.

Scoping limits what a compromised agent can reach

An agent that reads email processes untrusted input. A message body can carry instructions aimed at the agent rather than at you — a prompt injection — and a convincing one can get the agent to make API calls you never intended. Scoping decides how far those calls reach. The key is the boundary, so it holds whatever the agent’s reasoning does:

An inbox-scoped key confines the damage to the one inbox that received the message. Other inboxes, other tenants, and your account settings stay out of reach — the agent cannot read them, send from them, or delete them. It also cannot read or change the inbox’s sender rules, so who it may write to stays fixed regardless of what the injected instructions say.
An account-wide key on the same agent turns one malicious email into account-wide reach.

Give each agent an inbox-scoped key for the inbox it owns. Keep the account-wide key server-side, and use it only to provision and to mint the scoped keys.

Invalid authentication

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

Overview

Pods

Inboxes

Custom domains

Messages

Sender rules

Attachments

Feedback

Getting an API key

Key scopes

Security

Scoping limits what a compromised agent can reach

Invalid authentication

​Getting an API key

​Key scopes

​Security

​Scoping limits what a compromised agent can reach

​Invalid authentication

Getting an API key

Key scopes

Security

Scoping limits what a compromised agent can reach

Invalid authentication