Templates and variables

Building HTML strings in application code works until the day marketing wants a wording change and it needs a deploy. Store the template instead.

Syntax

Variables are {{ name }}, whitespace-tolerant. Dot notation reaches into nested objects.

<h1>Thanks, {{ first_name }}</h1>
<p>Shipping to {{ address.city }}, {{ address.country }}.</p>

One filter exists: default.

<p>Hello {{ first_name | default('there') }},</p>

Both quote styles work: default('there') and default("there").

A missing variable renders empty, never braces

If you do not supply first_name and give no default, the tag renders as an empty string. It never leaks {{ first_name }} into somebody's inbox — which is the failure mode that makes a company look careless, so it was ruled out by design rather than left to care.

That cuts both ways: a typo in a variable name fails silently. {{ frist_name }} produces nothing at all rather than an error. Preview before you send.

Escaping

Values are HTML-escaped in html bodies and left raw in subject and text. So a customer called Ada & Co renders correctly in HTML and is not an injection vector.

This means you cannot inject markup through a variable, deliberately. If you need a link whose URL comes from data, put the whole anchor in the template and pass only the URL — and be aware that a URL containing & will be escaped, which is correct in HTML.

Create a template

curl -X POST "$MAILYTE_BASE/api/v1/email-templates" \
  -H "Authorization: Bearer $MAILYTE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "order-shipped",
    "subject": "Your order is on its way, {{ first_name | default(\"there\") }}",
    "html": "<h1>On its way</h1><p>Tracking: {{ tracking_code }}</p>",
    "text": "On its way. Tracking: {{ tracking_code }}"
  }'

Variables work in subject as well as the bodies.

Preview before you send

curl -X POST "$MAILYTE_BASE/api/v1/email-templates/preview" \
  -H "Authorization: Bearer $MAILYTE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "template_id": "01JBT8XQ2M9WYC3K4F6R7S8T9V",
    "variables": { "first_name": "Ada", "tracking_code": "AC-9921" }
  }'

Worth calling from your own test suite. Because a missing variable renders empty rather than failing, a rename on one side and not the other produces a plausible-looking email with a hole in it — and preview is the cheapest place to catch that.

Send with a template

curl -X POST "$MAILYTE_BASE/api/v1/messages" \
  -H "Authorization: Bearer $MAILYTE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "ada@example.com",
    "from": "hello@yourdomain.com",
    "template_id": "01JBT8XQ2M9WYC3K4F6R7S8T9V",
    "variables": { "first_name": "Ada", "tracking_code": "AC-9921" }
  }'

Overriding

Fields you pass beat the template's. Send a subject alongside a template_id and yours wins, with your variables substituted into it. Useful for a one-off variant without forking the template.

Always send a text part

A message with only an HTML body is treated with suspicion by most spam filters, and is unreadable in the clients that prefer plain text. Write both. The text version does not need to be pretty — it needs to exist and say the same thing.

Next

Running a campaign — the same templates, to a whole list.