Pagination and filtering
Cursor paging
The default. Used by messages, suppressions, sandbox messages, quarantine and DLP events.
curl "https://api.lockally.com/v1/messages?limit=50" \
-H "Authorization: Bearer $LOCKALLY_API_KEY"
{
"data": [ ... ],
"next_cursor": "2026-10-15T18:22:04.117Z"
}
Pass it back as cursor and repeat until next_cursor is absent:
curl "https://api.lockally.com/v1/messages?limit=50&cursor=2026-10-15T18:22:04.117Z" \
-H "Authorization: Bearer $LOCKALLY_API_KEY"
The cursor is opaque. Today it happens to be the boundary row’s timestamp or email, but treat it as a token: pass back exactly what you were given and do not construct, parse or compare one.
There is no total. Cursor paging cannot tell you how many rows exist without counting them, so it does not pretend to. If you need a count, you are paging to the end.
Offset paging
GET /v1/mailboxes only.
curl "https://api.lockally.com/v1/mailboxes?limit=50&offset=100" \
-H "Authorization: Bearer $LOCKALLY_API_KEY"
{
"data": [ ... ],
"limit": 50,
"offset": 100,
"total": 412
}
limit is 1 to 200, default 50. You get a total, which is why the console
can show “412 mailboxes” and a page count.
Offset paging drifts under writes. If a mailbox is created while you are walking pages, rows shift and you can see one twice or miss one. For a consistent snapshot, page quickly or tolerate the overlap.
Filtering
Filters are per endpoint, not global. The ones on GET /v1/messages are
representative:
| Parameter | Effect |
|---|---|
status |
queued, sending, delivered, bounced, deferred, complaint |
sender |
Exact match on the from mailbox |
q |
Free text across subject and sender |
since |
RFC 3339 instant, inclusive |
limit |
Page size |
Each resource page lists its own. Combining filters narrows: they are ANDed, not ORed.
There is no sorting
No endpoint accepts a sort, order or order_by parameter. Each list
has one fixed order, chosen for the endpoint:
- Messages, newest queued first.
- Threads, most recently active first.
- Mailboxes, by address.
If you need another order, sort client side after paging. This is a real limitation rather than an omission from these docs, and it is recorded as a gap.