> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paubox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dynamic templates

> Create reusable Handlebars email templates and send personalized messages through the Paubox Email API.

Dynamic templates let you store a Handlebars `.hbs` template on Paubox once and reference it by name when sending. Variable substitution, conditionals, and loops are resolved server-side before delivery, keeping your send requests small and consistent.

## Handlebars syntax

Templates use [Handlebars](https://handlebarsjs.com) syntax. The most common constructs:

| Syntax                        | Description                                      |
| :---------------------------- | :----------------------------------------------- |
| `{{variable}}`                | Insert the value of a variable                   |
| `{{#if condition}}...{{/if}}` | Conditional block (truthy check)                 |
| `{{#each items}}...{{/each}}` | Loop over an array; use `{{this}}` for each item |

## Example template

Save the following as `welcome.hbs`:

```handlebars theme={null}
Hello {{name}},

Thank you for signing up{{#if plan}} for the {{plan}} plan{{/if}}.

{{#if items}}
Your selected items:
{{#each items}}- {{this}}
{{/each}}
{{/if}}

The Paubox Team
```

## Workflow

### 1. Upload the template

Upload your `.hbs` file via `POST /dynamic_templates`. The `data[name]` value becomes the identifier you use when sending.

```bash theme={null}
curl -X POST https://api.paubox.com/v1/email/dynamic_templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "data[name]=welcome" \
  -F "data[body]=@welcome.hbs"
```

### 2. Send a templated message

Reference the template by name in `POST /templated_messages`. Pass variable values as a JSON string in `template_values`.

```bash theme={null}
curl -X POST https://api.paubox.com/v1/email/templated_messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "template_name": "welcome",
      "template_values": "{\"name\":\"Jane\",\"plan\":\"Pro\",\"items\":[\"Email API\",\"HIPAA Compliance\"]}",
      "message": {
        "recipients": ["jane@example.com"],
        "headers": {
          "subject": "Welcome to Paubox",
          "from": "noreply@YOUR_DOMAIN.com"
        }
      }
    }
  }'
```

<Note>
  `template_values` must be a JSON-encoded **string**, not a JSON object. Stringify it before including it in the request body.
</Note>

## Managing templates

| Operation             | API reference                                                    |
| :-------------------- | :--------------------------------------------------------------- |
| List all templates    | [List dynamic templates](/email-api/dynamic-templates)           |
| Create a template     | [Create a dynamic template](/email-api/dynamic-templates/create) |
| Get a template        | [Get a dynamic template](/email-api/dynamic-templates/get)       |
| Update a template     | [Update a dynamic template](/email-api/dynamic-templates/update) |
| Delete a template     | [Delete a dynamic template](/email-api/dynamic-templates/delete) |
| Send using a template | [Send a templated message](/email-api/templated-messages)        |