Authentication

The base URL is api.openemail.uk. Every request carries a workspace key, or the OAuth access token of an app a person connected, in an Authorization header.

Authorization: Bearer oe_live_9f2c1a4b7e05d3862c1f0a44_kX7…

Nothing else authenticates here. A session cookie and a session token are both refused with invalid_credential_type, which names the credentials it accepts rather than leaving you to guess at a bare 401.

GET /ping is the smoke test: it needs no scope and tells you what the key is.

curl "$OE/ping" -H "$AUTH"

{  "ok": true,  "keyId": "4c1b257a66287fd113bd89d0",  "mode": "live",  "scopes": ["emails:send", "emails:read"],  "roleId": null,  "grantedScopes": ["emails:send", "emails:read"],  "workspaceId": "10417196-e324-4283-af98-66ec62167c47"}

GET /addresses is the answer to a 403 you did not expect.

curl "$OE/addresses" -H "$AUTH"

{  "object": "list",  "unrestricted": false,  "data": [    { "object": "address", "address": "[email protected]", "enabled": true, "canSend": true },    { "object": "address", "address": "[email protected]", "enabled": true, "canSend": false }  ],  "domains": [    { "domain": "acme.com", "receivingVerified": true, "sendingVerified": true, "catchAll": false }  ]}

Revoking takes effect on the next call. The row stays on the keys page afterwards, so you can still tell whether anything was using the key when you killed it. The most useful state on that screen is "never used", because it is how a leaked key is told from a live dependency.

Rotating is the other way to retire a secret. It mints a new secret for the same key, so the id, the name, the scopes, the role, the send scope and every request and activity row all carry on; only the secret changes. The old one stops working the instant the rotation completes, with no overlap window, and the replacement is shown once. From the console it is in the same menu as Revoke and asks you to re-verify first. A key holding keys:write can also rotate itself with POST /keys/self/rotate, which is how an integration rotates on a schedule without anyone opening the console.

Other keys can be managed over the API too, behind scopes no key holds unless somebody gave it one: keys:read lists keys and reads their request log and activity, and keys:manage creates, changes, rotates, revokes and deletes them, never wider than the key making the call. The API keys page has the rules.

A key can be held to the places it is used from. ipAllowlist on POST /keys and PATCH /keys/{id} takes up to 50 IP addresses and ranges, such as 203.0.113.7 or 2001:db8::/32, and every call or SMTP sign-in from anywhere else is refused with 403 ip_not_allowed. An empty list lets the key work from anywhere again. A key cannot change its own list, and a key with a list can only give the keys it makes a list inside its own. Set it in the console on the page of the key, under Edit.

An app a person connected over OAuth receives an access token, and the same token authenticates here. It is held to the approval the person gave: one workspace, the permissions they chose intersected with their role, and any domains or addresses they picked. A member’s token reaches only the addresses that member reaches, the ones they were granted or every address when their role holds addresses:all, and sends only from the ones they may send from.

GET /ping answers "kind": "oauth" and the app’s clientId for one. An Idempotency-Key is honoured per person. Calls made with a token are not in the per-key request log: they are in the log of the app, which the person reads under Connected apps or with GET /account/connected-apps/{clientId}/requests. Operations that belong to a key or to the owner, such as rotating a key or managing API keys, are refused for anyone else with api_key_only or owner_only, and so is managing webhooks for a member whose role does not reach every address.

The web app asks a person for a verification code before a change that could lock them out or leak their mail, and an app acting for them with an OAuth access token is asked the same thing. Until the app has verified a code, the operations below answer 403 step_up_required and change nothing. One verified code unlocks all of them for that app for 60 minutes. An API key is never asked for a code.

The check runs after the scope, the request body and the resource itself have been checked, so a 422 or a 404 still means what it says, and before anything is written.

1. 1Ask for a code with POST /security/step-up. method says where it comes from. email means a six-digit code has just gone to the address the person signs in with, shown masked in sentTo. totp means they have two-factor sign-in on, so they read the code from their authenticator app or use one of their backup codes, and nothing is sent.
2. 2Ask the person for the code and send it to POST /security/step-up/verify as { "code": "…" }.
3. 3Repeat the call that was refused. elevatedUntil in the answer says when the app will be asked again.

curl -X POST "$OE/security/step-up" -H "$AUTH" {  "object": "step_up_challenge",  "method": "email",  "sentTo": "a•••@acme.com",  "reused": false}

curl -X POST "$OE/security/step-up/verify" -H "$AUTH" \  -H "Content-Type: application/json" \  -d '{ "code": "482913" }' {  "object": "step_up",  "elevated": true,  "elevatedUntil": "2026-09-26T11:42:07.000Z"}

GET /security/step-up says where the app stands without sending anything: elevated, elevatedUntil, the method the next code will use, and minutes, the length of the window. Check it before a run of changes, so the person is asked once at the start rather than halfway through. None of the three calls needs a scope, and an API key calling any of them gets 400 step_up_not_applicable.

• —An emailed code works for 10 minutes. Asking again while one is waiting and still has tries left reuses it, sends nothing and answers reused: true. Send { "resend": true } for a fresh code, which stops the waiting one from working.
• —A wrong code is 400 step_up_code_invalid, and the message says how many tries are left. The fifth wrong code is 429 step_up_locked, and so is every try after it. A locked code is never reused, so a plain POST /security/step-up starts a fresh one, with no resend needed.
• —An expired code, or a verify with no code waiting, is 400 step_up_code_expired. Ask for a new one with POST /security/step-up.
• —Each app has a budget of its own with each person: 5 codes an hour and 20 in 24 hours. The next request is 429 step_up_throttled, and the message says when to try again. A reused code does not count, and neither does one whose email could not be sent. The person’s other apps and the web app, which allows 10 codes an hour, never use it up. When the email cannot be sent the answer is 503 step_up_undeliverable, and no code is left waiting.
• —The 60 minutes belong to the person and this app together. Another app they connected is asked on its own, and revoking the app, or removing it in Account → Connected apps, ends the window at once. The person can also start the 60 minutes there with no code from the app: they choose Allow changes for 60 minutes in the app’s menu, after verifying on the website themselves, and End allowed changes stops them early.
• —Wrong codes also count against the app for 24 hours, across every code it asked for, and a correct code does not clear them. The tenth pauses verification for that app: asking for a code and verifying one both answer 429 step_up_locked, with a message that says it is paused until a given time, and until then even a correct code is refused. The person gets one email about it that names the app. Wrong codes from all of the person’s apps also count together: 20 in 24 hours pause verification the same way for every app they connected, even one that sent none of them, and removing an app does not lift that pause. Codes entered on the website count toward neither pause, and the person can still verify there.
• —An authenticator code is accepted once. Entering one that was already accepted, by any app or in the web app, counts as a wrong code, so wait for the next one.
• —The email with the code says a connected app asked for it, and shows the name the app registered with, its client ID, when the person connected it and, when it was refused in the last 15 minutes, the change it last asked to make. It also says that the code unlocks more than that one change: for 60 minutes the app can make any change on the list above that the person gave it access to. The name is chosen by whoever registered the app, so it is never proof of who is asking.

The MCP server asks the same. Each tool in the table makes the change of the operation beside it, and until the app has verified a code it answers with an ordinary tool result whose text starts Refused (step_up_required):, and changes nothing. The app verifies a code with the same access token, through the calls above, and calls the tool again. A client that cannot make those calls asks the person to choose Allow changes for 60 minutes on it in Account → Connected apps, as the refusal says. REST and the tools share the 60 minutes, so one code covers both. emptyAudience, like POST /audiences/{id}/empty, never asks.

{  "content": [    {      "type": "text",      "text": "Refused (step_up_required): This action needs a verification code. Ask for one with POST /security/step-up, send it to POST /security/step-up/verify with the same access token, then call the tool again. If you cannot make those calls, ask the person to choose Allow changes for 60 minutes on this app in Account settings, Connected apps, on the Nextmail website, then call the tool again."    }  ]}