Conventions
What holds true for every endpoint, so the per-resource pages do not repeat it.
Base URLs
| Host | What it serves |
|---|---|
https://api.lockally.com |
The REST API. Everything under /v1. |
https://api.lockally.com/scim/v2 |
SCIM 2.0 provisioning. Not under /v1: the path is fixed by RFC 7644. |
https://mcp.lockally.com |
The MCP server, streamable HTTP. See MCP server. |
app.lockally.com is the console and mail.lockally.com is webmail. Neither
accepts API calls, and pointing a client at one is a common first-day error:
you get HTML or a redirect rather than JSON.
Request headers
| Header | When | Notes |
|---|---|---|
Authorization: Bearer lk_live_... |
Every request | Or lk_test_ for a test key |
Content-Type: application/json |
Any request with a body | |
Idempotency-Key |
Required on POST /v1/send, /v1/send/batch, and the agent write endpoints |
Any unique string per operation, 24 hour window |
There is no API version header. See Versioning.
Response formats
Success is application/json. Failure is application/problem+json, to
RFC 9457.
{
"type": "about:blank",
"status": 403,
"title": "Insufficient scope",
"detail": "This endpoint requires scope: send:write",
"code": "insufficient_scope",
"request_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
}
code, when you need to tell two errors apart
Some errors carry a stable code. It is lowercase snake_case, it will never
be reworded, and it is the right thing to branch on. title is English prose
and will change.
code |
Status | Means |
|---|---|---|
insufficient_scope |
403 |
The key is valid; it lacks the scope detail names. Create a new key, scopes cannot be added to an existing one |
business_mode_required |
403 |
The endpoint needs hosted mailboxes and the account is Lockally API. No scope fixes this, see modes |
The list is deliberately short. Every published code is permanent, so
only conditions a client would genuinely handle differently get one. Errors
without a code are distinguished by status and detail. If you need to
branch on one that has no code, ask and we will add it rather than leaving
you parsing prose.
Status codes
| Code | Meaning here |
|---|---|
200 |
Succeeded. On POST /v1/send this means nothing was queued |
201 |
Created |
202 |
Accepted into the queue. This is the success you want from a send |
204 |
Succeeded, no body |
400 |
Malformed request |
401 |
Key missing, invalid, revoked, or the wrong kind |
403 |
Scope missing, or the account is the wrong product |
404 |
Not found, or not visible to this key |
409 |
Conflicts with current state. detail names the recovery route |
422 |
Parsed but not valid |
429 |
Rate cap or warm-up cap. Honour Retry-After |
5xx |
Our fault. Safe to retry with the same Idempotency-Key |
The 200 on a send is the one that bites. It means every recipient was
suppressed, or the key was a test key. Both are successes and neither
delivers anything. See Understanding responses.
Dates and ids
Timestamps are RFC 3339 in UTC (2026-10-16T09:12:44Z).
Ids are UUIDs, except the Internet Message-ID, which is the
<local@domain> form and appears as rfc_message_id. The two are not
interchangeable: id is what GET /v1/messages/{id} takes.
Request ids
Every response carries X-Request-Id, and every error repeats it in the
body as request_id. Quote it in a support report and the call can be found
exactly.
It is in the body as well as the header on purpose: most people log response bodies and few log headers.
X-Request-Id: 0f8fad5b-d9cb-469f-a165-70867728950e
You can supply your own. Send X-Request-Id and it is echoed back, so
one id threads through your logs and ours. It must be 64 characters or fewer
and only letters, digits, -, _ or .; anything else is replaced with a
generated id rather than echoed.
This covers requests that never reach a handler. A 401 has a request id,
which matters because an authentication failure was previously the one thing
with nothing to quote.