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.