Templates and personalization
Store a message once and send it with values filled in, instead of building the body in your application every time.
{
"from": "receipts@yourcompany.com",
"to": ["alice@example.com"],
"template_id": "8c1d4f2a-6b3e-4d19-9a27-5e0f1c8b7a44",
"variables": {
"name": "Alice",
"order_id": "12345"
}
}
The template supplies the subject and body; variables fills its placeholders.
Manage templates with GET /v1/templates and the rest of the
templates endpoints.
Template and inline content are mutually exclusive
Send template_id together with any of subject, text or html and the
request is rejected:
{
"status": 400,
"title": "Template conflict",
"detail": "Provide either template_id or inline subject/text/html, not both."
}
There is no partial override. You cannot keep a template’s body and replace just its subject; the template owns all three fields or none of them.
The placeholder syntax
Placeholders are {{name}}, Mustache-style. Whitespace inside the braces is
tolerated, so {{ name }} is the same placeholder. Names may contain letters,
digits, underscores, dots and hyphens.
It is deliberately not a template language. There are no conditionals, no loops, no sections and no partials, only substitution. A template is authored by a tenant and rendered on our servers, so anything more expressive would be a way to run logic inside the platform.
| Behaviour | |
|---|---|
| Placeholder with a matching variable | replaced with the value |
| Placeholder with no matching variable | replaced with an empty string |
| Variable with no matching placeholder | ignored |
Values are escaped in HTML, and not in text
When rendering the html field, substituted values are HTML-escaped, so a
variable containing <b> arrives as visible text rather than markup. That is
what stops a value from injecting layout into your template.
The text and subject fields are not escaped, which is correct for
plain text but means a value containing a newline would end a subject line
early. Strip control characters from anything you pass as a subject variable.
Personalization is per send, not per recipient
This is the limit worth understanding before you design around templates.
variables applies to the whole request. A send with ten recipients
renders the template once and delivers the identical body to all ten:
{
"to": ["alice@example.com", "bob@example.com"],
"template_id": "...",
"variables": { "name": "Alice" }
}
Bob receives a message addressed to Alice. There is no per-recipient variable map and no mail-merge.
Genuine personalization means one message per recipient. Use
batch sending, which takes up to 500 independent messages in
one call, each with its own recipient and its own variables:
{
"messages": [
{
"from": "receipts@yourcompany.com",
"to": ["alice@example.com"],
"template_id": "8c1d4f2a-6b3e-4d19-9a27-5e0f1c8b7a44",
"variables": { "name": "Alice", "order_id": "12345" }
},
{
"from": "receipts@yourcompany.com",
"to": ["bob@example.com"],
"template_id": "8c1d4f2a-6b3e-4d19-9a27-5e0f1c8b7a44",
"variables": { "name": "Bob", "order_id": "12346" }
}
]
}
That also gives each recipient their own message id, delivery event and bounce, which a single multi-recipient send cannot.
Variables are strings
variables is a flat map of string to string. There are no nested objects, no
arrays and no numbers: format values in your application before sending them.
A non-string value does not render as blank, it rejects the whole request
with 400 Invalid JSON body before anything else is looked at. Quote it:
"49.99", not 49.99. null is the exception and renders as an empty string.
Going further
This page covers sending with a template. The rest of the template surface has its own section:
- Creating email templates and template IDs
- Template variables in full, including why a dot is not a path
- Logic, conditionals and defaults, none of which exist
- Template versions: every save is kept, and how to roll one back
- Previewing and testing rendered emails
- Template errors
Personalising per recipient
This is the part that catches people out, and the reason is simpler than it
looks: one email message has one body. That is RFC 5322, not a Lockally
limitation. A single POST /v1/send with ten addresses in to is one message,
so variables are rendered once and all ten recipients receive identical
content.
For per-recipient content you need one message per recipient, which is what
POST /v1/send/batch is:
curl -X POST https://api.lockally.com/v1/send/batch \
-H "Authorization: Bearer $LOCKALLY_API_KEY" \
-H "Idempotency-Key: welcome-run-9981" \
-H "Content-Type: application/json" \
-d '{
"variables": { "brand": "Acme", "year": "2026" },
"messages": [
{ "from": "hello@yourdomain.com", "to": ["ada@example.com"],
"template_id": "...", "variables": { "first_name": "Ada" } },
{ "from": "hello@yourdomain.com", "to": ["grace@example.com"],
"template_id": "...", "variables": { "first_name": "Grace" } }
]
}'
The top-level variables are shared defaults. Every message inherits them,
and each message’s own variables override them key by key. Without that, a
500-message batch repeats brand and year 500 times: most of the payload,
and 500 places for one of them to differ by a typo.
Each message is rendered, validated and enqueued on its own, and a bad one fails only its own slot. A batch is capped at 500 messages.