Simulating failures
A delivered event proves the happy path, which is the path least likely to break. The failures are what your handler needs to survive.
Delivery outcomes you can force
Send with a test key, take the id from the response, then:
curl -sS -X POST \
"https://api.lockally.com/v1/sandbox/messages/$ID/simulate" \
-H "Authorization: Bearer $LOCKALLY_TEST_KEY" \
-H "Content-Type: application/json" \
-d '{"event":"bounced","reason":"550 5.1.1 unknown recipient"}'
Scope: send:write.
event |
Webhook raised | Message status becomes |
|---|---|---|
delivered |
delivery.delivered |
delivered |
bounced |
delivery.bounced |
bounced |
deferred |
delivery.deferred |
deferred |
complaint |
delivery.complaint |
complaint |
reason is free text and is carried through to the event, so you can assert
your handler parses what it is given rather than what you hoped it would get.
delivered is in the list deliberately: it lets you re-drive a handler without
sending again.
The event is raised through the real publisher, so it arrives with the same
envelope, the same t=,v1= signature and the same retry behaviour as a
production event. Your verification code is genuinely exercised. See
Signature verification.
Inbound messages you can inject
POST /v1/test/inbound
{ "mailbox": "support@yourdomain.com", "from": "customer@example.com",
"subject": "Help", "text": "My order never arrived",
"in_reply_to": "<...>", "references": ["<...>"] }
Scope: inboxes:write, and it refuses anything but a test key with 403.
The message goes through the real indexing path, so threading works: supply
in_reply_to and the message joins the thread it is replying to, exactly as a
real reply would. The response returns thread_id, message_id and
rfc_message_id.
This is how to exercise an agent loop (webhook, read thread, draft, approve) without anyone emailing you. See Connect an agent.
Error responses you can provoke
These need no special mode. They are ordinary bad requests:
| Want | Send |
|---|---|
400 invalid body |
malformed JSON, or variables with a non-string value |
401 |
a key that does not exist, or a live key in lk_test_ form |
403 wrong scope |
a key without send:write |
403 sender |
a from on a domain you have not verified |
404 |
a template_id that does not exist |
Two that developers reach for and will not find:
There is no 409 on a reused Idempotency-Key. A replay returns the
FIRST response, whatever body you send the second time. Do not write a test
that asserts a conflict; assert that the replay matches the original.
An all-suppressed send is not an error. It returns 200 with
"status": "suppressed" and a warning, on a test key and a live key alike,
because it is a success no-op rather than something to retry.
What you cannot simulate
Stipulated rather than worked around, because guessing here wastes a day.
Rate limiting and allowance exhaustion. Test sends are excluded from both
counts by design, so you cannot drive a test key into a 429. Exercising your
backoff code means either a live key at volume or a stub in your own client.
Reputation throttling. Same reason: test rows are excluded from every
reputation count, so you cannot push a workspace into throttled with test
traffic and watch your handling of it.
A real MTA rejection. simulate writes the outcome you ask for. It does
not open an SMTP session, so it cannot reproduce a specific remote server’s
wording, timing or multi-stage failure. If you need the exact text a particular
provider returns, you need a real send to that provider.
Webhook delivery failure. There is no way to ask the dispatcher to fail delivering to your endpoint. To exercise your own retry and replay handling, take your endpoint down and send a test event into it, then read The event log.
Inbound attachments, HTML and headers. POST /v1/test/inbound takes
text only, plus the threading fields. You cannot inject an inbound message
with an attachment, an HTML part or custom headers, so an agent whose logic
depends on those cannot be fully exercised this way.