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.

      Understanding responses

      Three things about Lockally responses surprise people, and all three cause bugs that look like something else.

      A 2xx is not one answer

      202 Accepted   the message was queued and will be delivered
      200 OK         the call succeeded and NOTHING was queued

      A 200 from POST /v1/send means one of two things: every recipient was already suppressed, or you used a test key and the send was simulated. Both are legitimate successes. Neither produces a delivery.

      There are two message ids and they are not interchangeable

      Field What it is Use it for
      id The Lockally id, a UUID GET /v1/messages/{id}, webhook correlation
      rfc_message_id The Internet Message-ID, <...@...> Matching against mail headers and bounces at other providers

      Delivery events carry the Lockally id as message_id. That has not always been true: until recently it depended on which part of the pipeline raised the event, and delivery.bounced had two shapes. It is consistent now, and rfc_message_id carries the Internet one. See the changelog if you wrote code against the old behaviour.

      Errors are RFC 9457 problem documents

      Every failure is application/problem+json:

      {
        "type": "about:blank",
        "title": "Insufficient scope",
        "status": 403,
        "detail": "This endpoint requires scope: send:write"
      }

      detail is the field worth reading and logging. On a 403 it names the exact scope the key is missing. Logging only the status code throws away the one piece that tells you what to fix.

      The ones you will actually meet:

      Status Means What to do
      401 Key missing, invalid, revoked, or wrong kind Check the key and its prefix
      403 Scope missing, or wrong account mode Read detail. A new key, or add business mail
      409 The thing already exists, or is in a state that refuses this Read detail, it names the recovery route
      422 The request parsed but is not valid Fix the field detail names
      429 Rate cap or warm-up cap Honour Retry-After

      Retrying without sending twice

      POST /v1/send requires an Idempotency-Key. Any unique string per send, with a 24 hour dedupe window. Repeat the same key and you get the original response back byte for byte, and no second message.

      Derive the key from the thing you are sending, not from the attempt. order-1042-shipped is right. A fresh UUID per retry defeats the entire mechanism, because each attempt looks like a new send.

      Rate limits and warm-up

      A 429 carries Retry-After in seconds. Honour it: retrying into a cap extends the window rather than shortening it.

      Accepted sends may also carry warm-up headers while the platform is ramping its outbound reputation:

      X-Warmup-Day         X-Warmup-Daily-Cap         X-Warmup-Used-Today

      These describe a platform-wide cap shared by every account, not your own allowance, and they disappear once the ramp finishes. Hitting the cap returns 429.

      Paging

      There are two styles, and which one you get depends on the endpoint.

      Most lists are cursor paged: pass the next_cursor from one response as cursor on the next, and stop when it is absent. Do not construct a cursor yourself.

      GET /v1/mailboxes is offset paged instead, with limit, offset and a total. Code written to assume one style breaks on the other, so check Pagination for which applies.

      Next