Lockally

      Use your API key in the examples

      Replaces lk_live_… in the code samples on this site so you can copy and run them. It is stored in this browser only and is never sent anywhere, including to Ask AI.

      It will be visible on the page. Use a test key if you are sharing your screen or taking screenshots.

      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.