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.

      Your development environment

      You can build the whole integration without delivering a single message to a real person, and without a verified domain. A test send from an unverified domain is accepted and comes back with a warning saying a live key would refuse it, so the one thing you still have to do before going live is never a surprise. See Development and production.

      Use a test key

      Create a key with "test": true and it is issued with an lk_test_ prefix. A test key runs the full loop: validation, grants, threading, drafts and webhooks all behave exactly as they do in production.

      What is different is the end of it. The message is recorded as delivered without ever reaching the mail server, a simulated delivery.delivered webhook fires so your handler is testable, and nothing counts against your rate cap, monthly allowance, send units, warm-up or reputation.

      curl -X POST https://api.lockally.com/v1/api-keys \
        -H "Authorization: Bearer $LOCKALLY_ADMIN_KEY" \
        -H "Content-Type: application/json" \
        -d '{"label": "local dev", "scopes": ["send:write", "send:read"], "test": true}'

      Inspect what it captured, and force an outcome:

      curl https://api.lockally.com/v1/sandbox/messages \
        -H "Authorization: Bearer $LOCKALLY_TEST_KEY"
      
      curl -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": "mailbox full"}'

      event is one of delivered, bounced, deferred or complaint, and reason is optional. The stored message is updated to match, so a later read agrees with the webhook you just received.

      That last one is the useful part. Bounces and complaints are the paths nobody tests, because provoking a real one is awkward. Simulate them and make sure your webhook handler does the right thing before a real bounce arrives.

      Keep the key out of your code

      export LOCKALLY_API_KEY="lk_test_..."

      Read it from the environment, never from a literal. Keys are hashed at rest, so a leaked key cannot be looked up and re-shown; it can only be revoked and replaced.

      Never put a key in anything a user can download. No browser bundles, no mobile binaries. For those, mint short-lived tokens from your own backend.

      Install a client, or do not

      The API is plain HTTP and JSON, and curl is a complete client. The SDKs are convenience.

      npm install lockally          # TypeScript / JavaScript
      pip install lockally          # Python
      go get github.com/lockallyinc/lockally-go
      gem install lockally          # Ruby
      composer require lockally/sdk # PHP
      dotnet add package Lockally.SDK

      Eleven are published, with the full list and install commands on SDKs and libraries. They are generated from one spec, so a class is named for its API group (SendApi) and a method for what it does (sendEmail). See Code Examples for the same task in each.

      The CLI

      lockally is a command line client for sending, managing domains and mailboxes, and tailing logs. Useful for poking at the API without writing a program. Source and install instructions are in the lockally-cli repository.

      Receiving webhooks locally

      Your machine is not reachable from the internet, so point the subscription at a tunnel (ngrok, Cloudflare Tunnel, or similar) during development.

      Verify the signature even locally. It is the one piece most easily left until last and most easily got wrong, and a handler that skips verification in dev usually ships that way. See signature verification.

      Next

      1. Make your first request and confirm the key works.
      2. Send your first email with the test key.
      3. Go to production when the loop holds.