# 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:

```html
<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`):

```bash
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`:

```ts
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.

```ts
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`.
