Email template variables done right: declared, typed, versioned and escaped

Email template variables are the named, typed slots a stored email template declares — {{name}}, {{seats}} — that each send fills with a value. They are the mechanism behind email personalization: the content lives in the template, the facts about one recipient arrive with the send, and rendering joins the two.

The word declared is the whole difference between a template variable and a string you glued together in application code. A declared variable has a key, a type, and optionally a fallback, and the API checks a send against that declaration before anything is rendered. A value of the wrong type is refused. A key nobody declared is refused. A key the send forgot takes its fallback or is refused. None of those become an email with a bare placeholder in it.

The grammar is deliberately small. A placeholder is {{key}} or {{ key }}, with the key matching ^[A-Za-z0-9_]+$, and there is no logic, no filter and no nesting. Anything conditional belongs in the code that decides which template to send, and the templates page explains why that trade was made.

The alternative is to build the HTML in your own code — "Hello " + name, or a template literal — and post it as html. It works, and it is where most teams start. The table is what you give up by staying there.

The escaping row is the one with teeth. In application code, escaping is a habit, and habits have exceptions. In a template, string values are escaped in the HTML body without anyone deciding to, which is the subject of the last section.

A template is created as a draft with its content and the variables that content uses. Each variable is { key, type, fallback_value }, with type one of string, number, boolean, object or list, and a version may declare at most 200 of them.

curl https://api.rasket.com/templates \  -H "Authorization: Bearer $RASKET_API_KEY" \  -H "User-Agent: acme-billing/1.0" \  -H "Content-Type: application/json" \  -d '{    "name": "Welcome",    "alias": "welcome",    "from": "Acme <orders@send.acme.example>",    "subject": "Welcome to Acme, {{name}}",    "html": "<p>Hello {{name}}, your workspace has {{seats}} seats.</p>",    "text": "Hello {{name}}, your workspace has {{seats}} seats.",    "variables": [      { "key": "name", "type": "string", "fallback_value": "there" },      { "key": "seats", "type": "number", "fallback_value": 1 }    ]  }'

The alias is the handle your code will hold: lower-case letters, digits, - and _, at most 63 characters, never a UUID, unique among your live templates and freed when the template is deleted. Every template route and every send accepts either the id or the alias.

{
  "statusCode": 422,
  "name": "validation_error",
  "message": "Every {{key}} must be declared in variables, and every declared variable must be used.",
  "errors": [
    { "path": "html", "message": "{{plan}} is used in html but is not declared in variables." },
    { "path": "variables[1].key", "message": "Variable seats is declared but never used in subject, html or text." }
  ]
}

Creating a template writes version 1 as a draft, and nothing can be sent from it until it is published. Publishing makes the current version the one sends use. The first PATCH on a published template opens a new draft version; later edits write that same draft, and sends keep using the published version until you publish again.

# Edit a published template: this opens draft version 2curl -X PATCH https://api.rasket.com/templates/welcome \  -H "Authorization: Bearer $RASKET_API_KEY" \  -H "User-Agent: acme-billing/1.0" \  -H "Content-Type: application/json" \  -d '{ "subject": "Welcome aboard, {{name}}" }'
# See which version is current and which is publishedcurl https://api.rasket.com/templates/welcome/versions \  -H "Authorization: Bearer $RASKET_API_KEY" \  -H "User-Agent: acme-billing/1.0"
# Make version 2 the one sends usecurl -X POST https://api.rasket.com/templates/welcome/publish \  -H "Authorization: Bearer $RASKET_API_KEY" \  -H "User-Agent: acme-billing/1.0"
# Roll back: a new draft (version 3) copied from version 1, then publish itcurl -X POST https://api.rasket.com/templates/welcome/versions/1/restore \  -H "Authorization: Bearer $RASKET_API_KEY" \  -H "User-Agent: acme-billing/1.0"

The versions list marks two things per entry: current is the version you read and edit, and published is the one sends use. When they differ, retrieving the template shows the draft with has_unpublished_versions set to true.

• Rolling back is a restore followed by a publish. Restoring version 1 does not flip anything live: it copies that version into a new draft, which you publish when ready. A draft you had open stays in the list.
• Queued emails keep the version they resolved. Publishing takes effect for the next send, never for one already accepted.
• Every sent email records the template and the exact version it used, so what a customer received stays correct in your records however often the template changes afterwards.

That last point is why templates belong in the API rather than in a file: the record of what was sent is kept next to the send. The templates reference lists every route, including duplicate and delete.

A send names the template and its values, and carries no html or text of its own — the two cannot be combined. Values are strings or numbers of at most 2,000 characters; a declared key the request leaves out takes its fallback.

curl https://api.rasket.com/emails \  -H "Authorization: Bearer $RASKET_API_KEY" \  -H "User-Agent: acme-billing/1.0" \  -H "Idempotency-Key: welcome-user-8812" \  -H "Content-Type: application/json" \  -d '{    "to": ["ronald.williams@example.com"],    "template": {      "id": "welcome",      "variables": { "name": "Ronald", "seats": 12 }    }  }'

There is no from and no subject in the request because the template sets both. A request that sets them wins over the template; if neither does, the send is 422 missing_required_field. The idempotency key is derived from the user the welcome is for, so a retried sign-up cannot welcome them twice, and the emails reference has the rest of the request shape — attachments, tags, scheduling all work unchanged.

Two routes cover the two questions you have before publishing: what will this render as, and what does it look like in an inbox.

curl https://api.rasket.com/templates/welcome/preview \  -H "Authorization: Bearer $RASKET_API_KEY" \  -H "User-Agent: acme-billing/1.0" \  -H "Content-Type: application/json" \  -d '{ "variables": { "name": "Ada" }, "version": 2 }'
# 200# {#   "object": "template_preview",#   "version_number": 2,#   "subject": "Welcome aboard, Ada",#   "html": "<p>Hello Ada, your workspace has 1 seats.</p>",#   "text": "Hello Ada, your workspace has 1 seats.",#   "missing_variables": []# }

curl https://api.rasket.com/templates/welcome/test \  -H "Authorization: Bearer $RASKET_API_KEY" \  -H "User-Agent: acme-billing/1.0" \  -H "Idempotency-Key: welcome-test-v2" \  -H "Content-Type: application/json" \  -d '{ "to": ["ada@example.com"], "variables": { "name": "Ada", "seats": 3 } }'

Every value a send passes is data that came from somewhere, and often the somewhere is a customer: their name, their company, a field they typed into a form. Rendering that into an HTML body without escaping is the injection OWASP’s XSS prevention cheat sheet describes for untrusted data in an HTML context, and its rule is the one the renderer applies: encode the characters that mean something to an HTML parser before they land in the document.

Value sent:      <script>alert(1)</script>
In html:         &lt;script&gt;alert(1)&lt;/script&gt;
In subject:      <script>alert(1)</script>
In text:         <script>alert(1)</script>

Value sent:      {{seats}}
Everywhere:      {{seats}}   (inserted literally, never re-scanned)

• Strings are HTML-escaped in html and inserted raw in subject and text. Numbers and booleans are written out as they are.
• Objects and lists land as compact JSON, escaped in html. They are for the rare template that prints structured data, not for building markup.
• A substituted value is never re-scanned. A customer whose company is called {{seats}} gets exactly that text; the placeholder is not expanded. A value cannot introduce a placeholder, so nothing a customer types can drive the template.

Why the subject is not escaped: it is not HTML. A subject is a header, and the text body is a text/plain part; only the text/html part is parsed as markup, per the media types RFC 2046 defines. Entity encoding & into & in a subject line would show the reader the entity, not the ampersand. Escape for the context the value lands in, and no other.

What escaping does not do is make a template a safe place for raw markup from outside. If a customer-supplied field genuinely has to carry HTML, that is a decision to make in your code, with a sanitiser, before the value reaches the send; the template will escape it otherwise, which is the right default. The glossary has the short definition, and the Node walkthrough shows the same send from the typed client.