Logic, conditionals and defaults
Lockally templates do substitution and nothing else. This page states the three limits plainly, because each of them is a thing people reasonably expect and each fails silently rather than with an error.
There are no conditionals
There is no {{#if}}, no {{^unless}}, no ternary, no comparison. A template
cannot show one paragraph to a trial user and another to a paying one.
Written into a template, conditional syntax is rejected at save time.
{{#if premium}} is not a legal placeholder, because # is outside the
allowed character set, and saving a template containing one answers 400
rather than storing something that would reach the recipient as literal text.
Template validation has the message.
There are no loops or sections
No {{#each items}}, no repetition, no iteration over an array. A template
cannot render an order with a variable number of line items, because there is
no way to pass an array in the first place: variables is a flat map of string
to string, and a non-string value rejects the whole request. {{#each}} is
refused at save time for the same reason {{#if}} is.
There are no default values
No {{name|default}}, no {{name or "there"}}, no fallback of any kind. A
placeholder with no matching variable renders as an empty string, always.
Hello {{first_name}}, your order is ready.
With first_name missing, that sends as “Hello , your order is ready.” It is
not rejected and nothing is logged.
This is the one limit on this page with no save-time check behind it, because
there is nothing to check: {{first_name}} is a perfectly good placeholder
and only the caller knows whether it will be filled. What the API gives you
instead is the template’s
variables array,
so you can assert against it yourself.
Why
A template is authored by a customer and rendered on our servers. Substitution cannot do anything except copy a string into a string. The moment a template language gains branching, iteration or expression evaluation, a template becomes a program running inside the platform on our side of the trust boundary, and the question stops being “what does this render” and becomes “what can this reach”. That trade is not worth making for formatting that your application can do before it calls us.
This is a deliberate design decision rather than something on a roadmap.
What to do instead
Decide in your application, then send the text. Branching is a line of code where your data already lives:
const greeting = user.firstName || 'there';
await lockally.send({
from: 'hello@yourcompany.com',
to: [user.email],
template_id: WELCOME_TEMPLATE,
variables: { greeting, plan_name: user.plan }
});
Always send every key the template uses. Default values are the gap most likely to bite you, and filling them yourself is a few lines:
const DEFAULTS = { first_name: 'there', company: 'your team' };
const variables = { ...DEFAULTS, ...actual };
Doing it this way makes the default explicit in code, which is also where it
can be reviewed and tested. Pair it with a test that asserts the template’s
variables array is covered by the keys of DEFAULTS, and a placeholder
added to the template later cannot slip out unfilled.
For a handful of variants, use a template each. Two templates with the right names beat one template with a branch, and each can be previewed and tested on its own. Pick the id in your code.
For a genuinely variable body, build the HTML yourself and send it inline
with html instead of template_id. You lose the stored-template workflow and
gain complete control. The two are mutually exclusive on a single send, but a
batch can mix template-rendered and inline messages freely.