Template variables
Placeholders are {{name}}. At send time each one is replaced with the
matching entry from the request’s variables map.
{
"template_id": "8c1d4f2a-6b3e-4d19-9a27-5e0f1c8b7a44",
"variables": { "first_name": "Alice", "order_id": "12345" }
}
The syntax
Whitespace inside the braces is tolerated, so {{name}} and {{ name }} are
the same placeholder.
A name may contain letters, digits, underscores, dots and hyphens. Anything else, including a space inside the name, means the text is not recognised as a placeholder at all and is sent to the recipient literally.
| Written in the template | Treated as |
|---|---|
{{first_name}} |
placeholder first_name |
{{ first_name }} |
placeholder first_name |
{{first-name}} |
placeholder first-name, a different one |
{{first name}} |
not a placeholder, sent as written |
{{first_name} |
not a placeholder, sent as written |
Values must be strings
variables is a flat map of string to string. There are no nested objects, no
arrays, no numbers and no booleans.
This is stricter than it first appears. A non-string value does not render as blank, it rejects the entire request:
{ "variables": { "order_total": 49.99 } }
{
"status": 400,
"title": "Invalid JSON body",
"detail": "json: cannot unmarshal number into Go struct field sendRequest.variables of type string"
}
Format every value in your application first: "49.99", "3", "true".
null is the one exception. It decodes without error and renders as an empty
string, exactly like a variable you did not send.
Three ways a variable does nothing
All three are silent. None of them is an error, and none of them is reported anywhere.
A placeholder with no matching variable renders as an empty string. A
misspelt {{frist_name}} against a variable called first_name produces
“Hello ,” in the recipient’s inbox. Nothing warns you at authoring time or at
send time.
A variable with no matching placeholder is ignored. Sending
{"frist_name": "Alice"} to a template that uses {{first_name}} is the same
failure seen from the other end, with the same silent result.
A malformed placeholder is sent as written. {{first name}} reaches the
recipient as the literal characters {{first name}}.
Because none of these fail, the only way to catch them is to look at a rendered message. Testing rendered emails shows how to do that without sending anything to a real person.
Escaping
| Field | Substituted values are |
|---|---|
html |
HTML-escaped |
text |
not escaped |
subject |
not escaped |
Escaping the HTML field is what stops a value from injecting markup. A variable
containing <b>bold</b> arrives as visible text, not as formatting. You cannot
turn this off, and a variable is therefore not a way to pass a fragment of HTML
into a template.
The unescaped fields are correct for plain text but mean a value carrying a newline will end a subject line early. Strip control characters from anything you pass as a subject variable.
Discovering what a template needs
Every template carries a variables array: the distinct placeholders it
references across subject, HTML and text, in first-seen order.
{
"id": "8c1d4f2a-6b3e-4d19-9a27-5e0f1c8b7a44",
"name": "Order receipt",
"subject": "Your order {{order_id}}",
"html": "<p>Thanks {{first_name}}, we have your order.</p>",
"text": "Thanks {{first_name}}.",
"variables": ["order_id", "first_name"],
"created_at": "2026-10-20T09:14:22Z",
"updated_at": "2026-10-20T09:14:22Z"
}
It is derived from the body on every read rather than stored, so it follows an
edit immediately and can never disagree with the template it describes. A
template with no placeholders reports [], never null.
It is a checklist, not a contract. Nothing marks a variable as required, because nothing can: a missing one renders as an empty string rather than failing. What the field gives you is the ability to compare a template against the keys your code supplies, which is the only way to catch either half of the silent-failure pair above.
const tpl = await lockally.templates.get(id);
const missing = tpl.variables.filter((v) => !(v in myVariables));
if (missing.length) throw new Error(`template ${id} also needs: ${missing}`);
The console shows the same list above the preview while you edit.