Testing rendered emails
The useful property of a test key for template work is not that it is safe. It is that the template is rendered by the real code path before the send stops.
A test-key send resolves template_id, substitutes the variables, stores the
rendered message, and then diverts instead of delivering. So the stored body is
the exact subject, HTML and text that would have gone out.
Render a template and read it back
1. Send with a test key.
curl -X POST https://api.lockally.com/v1/send \
-H "Authorization: Bearer $LOCKALLY_TEST_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "receipts@yourcompany.com",
"to": ["anyone@example.com"],
"template_id": "8c1d4f2a-6b3e-4d19-9a27-5e0f1c8b7a44",
"variables": { "first_name": "Alice", "order_id": "12345" }
}'
{
"id": "0b9a7c3e-4d51-4a2f-9c18-6e77b2f10d93",
"message_id": "<0b9a7c3e-4d51-4a2f-9c18-6e77b2f10d93@test.lockally.com>",
"status": "delivered"
}
The recipient address does not have to exist. Nothing is transmitted.
2. Read the rendered message.
MESSAGE_ID=0b9a7c3e-4d51-4a2f-9c18-6e77b2f10d93 # the id from the send above
curl -s https://api.lockally.com/v1/messages/$MESSAGE_ID \
-H "Authorization: Bearer $LOCKALLY_TEST_KEY"
The response carries subject, html and text after substitution. Assert on
them, diff them against a fixture, or just read them.
This needs send:write for the send and send:read for the read. It does not
need templates:read.
Why this beats the console preview
Both show you rendered output. The difference is provenance: the console computes its preview in the browser, while this is the platform’s own renderer producing the bytes it would have transmitted. For a test you are going to trust in CI, use this one.
It is also the only way to check the whole chain at once. A test-key send exercises template resolution, variable substitution, escaping and send validation together, so it catches a template that renders fine and then fails validation, which a preview cannot.
What to assert
The two silent failures from Template variables are worth a test each:
const sent = await lockally.messages.get(id);
// A placeholder nobody filled renders as nothing.
assert(!sent.html.includes('{{'), 'literal placeholder left in the body');
assert(!/>\s*,/.test(sent.html), 'looks like an empty variable before a comma');
// And the subject actually got its value.
assert(sent.subject === 'Your order 12345');
The first check catches a malformed placeholder, which is sent literally. The second is a cheap stand-in for “a variable rendered empty”, which otherwise looks like perfectly valid output.
A stricter version, worth running once per template rather than per send: fetch
the template, extract its placeholder names with
/\{\{\s*([\w.-]+)\s*\}\}/g, and assert that the set equals the keys your code
supplies. That catches both halves at the source instead of inferring them from
rendered text.
What a test key does not tell you
- Nothing about deliverability. The message never reaches a mail server, so there is no SMTP response, no bounce and no inbox placement.
- Nothing about rendering in a mail client. You get the HTML, not a picture of Outlook.
- No usage. Test sends count against nothing: not your allowance, not the rate limit, not your reputation.
Template errors still apply
Test mode does not relax validation. An unknown template_id, a non-string
variable, or template_id sent alongside inline content all fail on a test key
exactly as they would on a live one, which is the point.
See Template errors.