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
-
Verify your sending domain. Publish the DNS records and confirm. Allow for propagation; this is the step that cannot be hurried.
-
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.
-
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.
-
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.
202is queued,200is not. - Set an
Idempotency-Keyderived from what you are sending, not from the attempt. A fresh value per retry defeats it and sends twice. - Honour
Retry-Afteron a429. 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.bouncedanddelivery.complaint, not justdelivered. 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 returns429.
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
detailfield on failures. On a403it names the exact scope you are missing, and a status code alone throws that away. - Store the Lockally
idagainst your own records so you can correlate a webhook later. It is not the same asrfc_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.