Lockally

      Use your API key in the examples

      Replaces lk_live_… in the code samples on this site so you can copy and run them. It is stored in this browser only and is never sent anywhere, including to Ask AI.

      It will be visible on the page. Use a test key if you are sharing your screen or taking screenshots.

      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.