Debugging a failed request
1. The response itself
Every error is RFC 9457 application/problem+json:
{
"type": "about:blank",
"title": "Sender not allowed",
"detail": "yourdomain.com is not verified for this workspace.",
"status": 403,
"request_id": "9f2c1d84-..."
}
title and status are the stable pair to branch on. detail is written for
a person and its wording changes, so do not match on it.
2. The request id
Every response carries x-request-id, and every problem document repeats it in
request_id. Keep it: it is the only identifier that ties your call to our
logs, and it is the first thing support will ask for.
You may set the header yourself to correlate with your own tracing. It is echoed back when it is sane, and replaced with a fresh UUID when it is not: anything over 64 characters, or containing a space or a quote, is discarded rather than reflected. So assert that the header is present, not that it equals what you sent.
3. What the platform recorded
A 202 means we accepted the message, not that anybody received it. The next
question is what happened after.
curl -sS "https://api.lockally.com/v1/messages?limit=20" \
-H "Authorization: Bearer $LOCKALLY_KEY"
status moves through queued, then delivered, bounced or deferred.
A bounce_reason is attached when there is one, and it carries the stage the
failure happened at, so RCPT TO: 550 ... and DATA: ... are distinguishable.
See Temporary and permanent failures.
For a test send the status is delivered immediately, because the outcome is
final the moment it is accepted.
4. What we tried to tell you
If the request succeeded and your system still does not know about it, the question is webhook delivery rather than sending.
curl -sS "https://api.lockally.com/v1/events?type=delivery.bounced" \
-H "Authorization: Bearer $LOCKALLY_KEY"
Scope webhooks:read, Starter or above. The log holds what we sent, the
response we got and each attempt. See The event log.
The failures that look like something else
401 with a key you are certain is right. Check the prefix against the
key’s registration. A key created with "test": true must be presented as
lk_test_, and a live key as lk_live_. The mismatch fails authentication
rather than telling you the prefix is wrong.
403 on a send that worked yesterday. Either a scope changed, or the
domain’s verification lapsed. Scopes cannot be added to an existing key, so a
key issued before a scope existed cannot have it.
A 202 and no mail. With a test key, that is the whole design. Check the
message_id suffix: @test.lockally.com means nothing was ever going to be
delivered.
Mail to one provider only. That is deliverability, not the API. Start at Deliverability monitoring.
Asking for help
Quote the request_id, the endpoint, the timestamp with a timezone, and
whether the key was live or test. With those four, a request can be found. See
Support.