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
- Make your first request and confirm the key works.
- Send your first email with the test key.
- Go to production when the loop holds.