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.

      Going to production

      What actually changes

      Less than you might expect. The base URL, the request format and the responses are identical. Three things differ:

      Test key Live key
      Delivery Recorded, never sent Sent
      Limits Counts against nothing Rate cap, allowance, units, warm-up, reputation
      Domain Not required Must be verified

      The switch

      1. Verify your sending domain. Publish the DNS records and confirm. Allow for propagation; this is the step that cannot be hurried.

      2. Create a live key. You cannot convert a test key. Create a new one with the same scopes, and keep the test key for your test suite.

      3. Change the environment variable, not the code. If the key is read from the environment, going live is a config change. If it is in a literal anywhere, fix that first.

      4. Send one real message to yourself before pointing traffic at it.

      Readiness checklist

      Each of these is a real failure somebody has had.

      Sending

      • Branch on the status code, not on 2xx. 202 is queued, 200 is not.
      • Set an Idempotency-Key derived from what you are sending, not from the attempt. A fresh value per retry defeats it and sends twice.
      • Honour Retry-After on a 429. Retrying into a cap extends it.
      • Decide what happens when a send fails permanently. Queue it, alert, or drop, but choose rather than discover.

      Receiving the outcome

      • Subscribe to delivery.bounced and delivery.complaint, not just delivered. The failures are the ones that need handling.
      • Verify the webhook signature, including the timestamp. Checking only the digest leaves you open to a replay of a genuine event.
      • Sign the raw body, byte for byte. Re-serialising the JSON changes key order and the signature will never match.
      • Make your handler idempotent. A webhook can arrive more than once.
      • Return 2xx quickly and do the work asynchronously. A slow handler looks like a failing one.
      • Exercise a bounce before you ship, with POST /v1/sandbox/messages/{id}/simulate.

      Deliverability

      • DKIM, SPF and DMARC published and verified for every sending domain.
      • Respect the suppression list. It exists to stop you mailing addresses that already bounced or complained, which is what damages a sending reputation.
      • Expect X-Warmup-* headers while the platform ramps. They describe a platform-wide cap, not your allowance, and hitting it returns 429.

      Operational

      • Key in an environment variable or a secret manager. Never in a repo, a log line, a browser bundle or a mobile binary.
      • Know how to revoke. Keys are hashed at rest and cannot be re-shown, so the recovery path is always revoke and replace.
      • Log the detail field on failures. On a 403 it names the exact scope you are missing, and a status code alone throws that away.
      • Store the Lockally id against your own records so you can correlate a webhook later. It is not the same as rfc_message_id.
      • Watch status.lockally.com. It is probed from outside our infrastructure, so it keeps reporting during an outage.

      After you are live

      Delivery events are the signal worth watching. A rising bounce rate is the early warning for a reputation problem, and it is visible in GET /v1/messages/stats before it is visible in anything else.

      If something is wrong and it is not an incident on the status page, see developer support for which channel suits which problem.