Templates

Templates keep email content out of your code. Designers can edit them in the dashboard while your app sends them by a stable alias. Every edit creates a new version, and sends use the published version.

Syntax

Templates use Jinja syntax:

<p>Hi {{ first_name }},</p>
{% if items %}
<ul>
  {% for item in items %}
  <li>{{ item.name }}: {{ item.price }}</li>
  {% endfor %}
</ul>
{% endif %}

Variables in HTML are escaped automatically, so user input cannot inject markup. The subject and text body are templates too.

Create a template

In the dashboard open Developers → Templates, or use the API (scope templates):

curl https://api.voozin.com/v1/templates \
  -H "Authorization: Bearer $VOOZIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Password reset",
    "alias": "password-reset",
    "subject": "Reset your {{ product }} password",
    "html": "<p>Hi {{ first_name }}, <a href=\"{{ reset_url }}\">reset your password</a>.</p>",
    "text": "Hi {{ first_name }}, reset your password: {{ reset_url }}",
    "sample_data": { "first_name": "Ada", "product": "Acme", "reset_url": "https://acme.com/reset/abc" },
    "publish": true
  }'

An alias may contain lowercase letters, digits, _ and -.

Send a template

Pass template_id (the id or the alias) and variables instead of subject, html and text:

await voozin.emails.send({
  from: "Acme <no-reply@acme.com>",
  to: [user.email],
  template_id: "password-reset",
  variables: { first_name: user.firstName, product: "Acme", reset_url: url },
});

Add template_version to send a specific version instead of the published one.

Versions

  • POST /v1/templates/:id/versions adds a version with new content.
  • POST /v1/templates/:id/publish with { "version": 3 } makes it the one that sends.
  • GET /v1/templates/:id returns the template and its versions.

Preview

  • POST /v1/templates/:id/preview with optional version and variables renders a stored template (it defaults to the version's sample data).
  • POST /v1/templates/render with subject, html, text and variables renders content without saving it, useful for an editor preview.
const preview = await voozin.templates.render({
  subject: "Hello {{ name }}",
  html: "<p>Hello {{ name }}</p>",
  variables: { name: "Ada" },
});

List templates

GET /v1/templates returns data with each template's id, name, alias, published_version, latest_version and subject.