Testing API requests
Every endpoint behaves identically on a test key except /v1/send and
/v1/send/batch, which divert instead of delivering. So testing a read
endpoint is just calling it, and testing a send is calling it and then reading
back what it captured.
The shape of a send test
curl -sS -X POST https://api.lockally.com/v1/send \
-H "Authorization: Bearer $LOCKALLY_TEST_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"from": "receipts@yourdomain.com",
"to": ["buyer@example.com"],
"subject": "Order 1234",
"text": "Thanks for your order."
}'
{
"id": "0b9f...",
"message_id": "<0b9f...@test.lockally.com>",
"status": "delivered"
}
Three things are worth asserting on, and one is a trap.
Assert on status, not the HTTP code. A live send and a test send both
return 202. The body is what differs: queued against delivered. An
all-suppressed send returns 200 on either kind of key, so treat 200 and
202 alike as success and branch on status.
message_id ends @test.lockally.com on a test send. If you are asserting
that your test suite cannot possibly have sent real mail, that suffix is the
cheapest check.
id is what the sandbox endpoints take. Keep it if the test will go on to
inspect or simulate.
Reading back what it captured
curl -sS "https://api.lockally.com/v1/sandbox/messages?limit=10" \
-H "Authorization: Bearer $LOCKALLY_TEST_KEY"
Each entry carries the original request body alongside the stored message, so you can assert on what the API received as well as what it produced. This is the assertion that matters for template work, because the stored body is the real rendered output. See Testing rendered emails.
limit accepts 1 to 200.
Testing the endpoints that are not sends
Nothing diverts, so a test key against /v1/domains, /v1/templates,
/v1/suppressions and the rest reads and writes your real workspace data.
That is worth saying plainly: a test key is not a copy of your workspace.
POST /v1/templates with a test key creates a real template, and reads return
real data. Test mode suppresses delivery, not writes.
What it will not do is anything irreversible:
| Refused on a test key | |
|---|---|
DELETE on a real resource |
mailboxes, domains, templates, aliases, SCIM users |
| Payments | anything under /v1/billing/, and add-on cancellation |
POST /v1/admin/close-account |
all with 403 Not allowed on a test key.
Deletes that testing genuinely needs are still allowed, because undoing them costs nothing: webhook endpoints (registering a tunnel endpoint and removing it afterwards is the documented local flow), cancelling a scheduled message, removing a suppression you added on purpose, and discarding a draft.
The rule is irreversibility, not writes. If you want write isolation beyond
that, the tool is scopes: issue the CI key with send:write and send:read
and nothing else, so an unexpected call fails with 403 rather than
succeeding. See Permissions and least privilege.
Error responses
Every error is RFC 9457 application/problem+json with title, detail,
status and a request_id. Assert on status and, where you care, on the
machine-readable fields, never on detail, whose wording changes.
See Error handling and Debugging a failed request.