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.

      Live and test keys

      There are exactly two environments, and a key belongs to one of them for life:

      Prefix
      lk_live_ Real sends, real billing, real limits
      lk_test_ The whole request path runs, nothing leaves the platform

      Create a test key by passing "test": true:

      { "label": "ci", "scopes": ["send:write"], "test": true }

      Same URL, same code

      Both kinds use https://api.lockally.com. There is no separate sandbox host and no environment parameter. Swapping the key is the whole of the change, so the code path you exercise in tests is the one that runs in production.

      What a test key actually does

      A send with a test key is accepted, validated and recorded exactly as a live one. Then, instead of handing it to the mail server:

      • it is stored, so you can inspect it
      • a simulated delivery.delivered webhook fires, carrying "test": true
      • the response is still 202, but with "status": "delivered" rather than "queued", because for a test key the outcome is already final
      • the message_id ends @test.lockally.com
      • nothing counts against your rate cap, monthly allowance or send units

      So the full loop runs, including your webhook handler, without mail reaching anybody.

      Inspect what it captured with GET /v1/sandbox/messages, and force a different outcome with POST /v1/sandbox/messages/{id}/simulate when you want to exercise your bounce handling.

      The one place test is more permissive

      Sender authorisation. A live key must send from a verified domain (api mode) or a mailbox or alias on one (business and both). A test key may send from any address, and the response carries a warning naming the domain to verify.

      That exception exists because the check ran before the test-mode divert, so a workspace with no verified domain could not make a single test call, which was 23 of the 27 api-mode workspaces on the platform.

      It is the only divergence between the two kinds of key beyond delivery itself, and it is reported in the response rather than left to be discovered on the first live send.

      What a test key will not do

      Test mode suppresses delivery. It does not make the rest of your workspace a copy, so reads and writes are against real data, and POST /v1/templates creates a real template.

      Irreversible operations are refused with 403 Not allowed on a test key: DELETE on a real resource, anything under /v1/billing/, add-on cancellation, and closing the account. Deletes that testing needs stay allowed: webhook endpoints, scheduled messages, suppressions and drafts.

      The two cannot be mixed

      A key registered as live cannot be presented in lk_test_ form, or the reverse. The mismatch fails authentication:

      {
        "status": 401,
        "title": "Invalid API key",
        "detail": "Key mode (live/test) does not match its registration."
      }

      This matters more than it looks. The failure mode it prevents is a staging deployment configured with a live key and quietly mailing real customers. Here that cannot happen by accident: the prefix is part of the secret, so a key pasted into the wrong environment fails loudly on the first request rather than succeeding and sending.

      Make the prefix an assertion in your deployment. A one-line check that staging holds a key beginning lk_test_ is the cheapest safety you will ever add.

      A key cannot be converted

      Live and test is fixed at creation, like everything else about a key. Promoting something from staging to production means issuing a live key, not flipping a flag.

      What test keys are not

      Not a separate account. A test key belongs to the same tenant, sees the same domains, templates and suppression list, and writes to the same data. It is isolated in delivery and billing, not in data.

      Not free of the plan check. API keys are a plan feature, so an account without API access cannot use a test key either.

      Not a way to test deliverability. Nothing reaches a real mail server, so a test send proves your integration works and tells you nothing about whether your mail would arrive.