Templates

Create reusable email templates with variable substitution for consistent messaging across your application.

Create a Template

Create a new email template with support for variables.

POST /v1/templates

create-template.ts

const template = await client.templates.create({
  name: 'Order Confirmation',
  subject: 'Order #{{orderNumber}} confirmed',
  html: `
    <h1>Thanks for your order, {{firstName}}!</h1>
    <p>Order #{{orderNumber}} has been confirmed.</p>

    <h2>Items</h2>
    <ul>
      {{#each items}}
        <li>{{this.name}} - ${{this.price}}</li>
      {{/each}}
    </ul>

    <p><strong>Total: ${{total}}</strong></p>
  `,
  variables: [
    { name: 'firstName', type: 'string', required: true },
    { name: 'orderNumber', type: 'string', required: true },
    { name: 'items', type: 'array', required: true },
    { name: 'total', type: 'number', required: true },
  ],
  type: 'transactional',
});

Template Variables

Templates support Handlebars-style variable syntax for dynamic content.

Basic Variables

<!-- Template -->
<p>Hello, {{firstName}}!</p>

<!-- With variables: { firstName: 'John' } -->
<p>Hello, John!</p>

Conditionals

{{#if isPremium}}
  <p>Thanks for being a premium member!</p>
{{else}}
  <p>Upgrade to premium for more features.</p>
{{/if}}

Loops

<ul>
  {{#each items}}
    <li>{{this.name}}: ${{this.price}}</li>
  {{/each}}
</ul>

Equality Checks

{{#equals status "active"}}
  <span style="color: green">Active</span>
{{else}}
  <span style="color: gray">Inactive</span>
{{/equals}}

{{#notEquals role "admin"}}
  <p>Standard user access</p>
{{/notEquals}}

Context Scoping

{{#with user}}
  <p>{{firstName}} {{lastName}}</p>
  <p>{{email}}</p>
{{/with}}

Format Helpers

Built-in helpers for formatting dates and currency values:

<!-- Date formatting (default: YYYY-MM-DD) -->
<p>Order date: {{formatDate orderDate}}</p>
<p>Delivery: {{formatDate deliveryDate "MM/DD/YYYY"}}</p>

<!-- Currency formatting (default: USD) -->
<p>Total: {{formatCurrency total}}</p>
<p>Price: {{formatCurrency price "EUR"}}</p>

Helper	Syntax	Example Output
formatDate	{{formatDate date "MM/DD/YYYY"}}	06/15/2025
formatCurrency	{{formatCurrency amount "USD"}}	$42.50

Date Format Tokens

Token	Description	Example
YYYY	Full year	2025
MM	Month (zero-padded)	06
DD	Day (zero-padded)	15
HH	Hours (24h, zero-padded)	14
mm	Minutes (zero-padded)	30
ss	Seconds (zero-padded)	00

Variable Schema

Define your variable schema for validation and documentation:

Property	Type	Description
name	string	Variable name (required)
type	string	string \| number \| boolean \| array \| object
required	boolean	Whether the variable is required
defaultValue	any	Default value if not provided
description	string	Description for documentation

List Templates

GET /v1/templates

list-templates.ts

const { data } = await client.templates.list();

for (const template of data) {
  console.log(template.name, template.type);
}

Update Template

PATCH /v1/templates/:id

update-template.ts

const template = await client.templates.update('template_xxxxx', {
  subject: 'Updated: Order #{{orderNumber}} confirmed',
  html: '<h1>Updated content</h1>',
});

Preview Template

Render a template with sample data to preview the output before sending. The template is validated and rendered server-side.

POST /v1/templates/preview

preview-template.ts

const result = await client.templates.preview({
  html: `
    <h1>Hello {{firstName}}!</h1>
    {{#if isPremium}}
      <p>Thanks for being a premium member!</p>
    {{/if}}
    <p>Total: {{formatCurrency total}}</p>
  `,
  subject: 'Welcome, {{firstName}}!',
  variables: {
    firstName: 'Alice',
    isPremium: true,
    total: 42.50,
  },
});

console.log(result.html);
// <h1>Hello Alice!</h1>
// <p>Thanks for being a premium member!</p>
// <p>Total: $42.50</p>

console.log(result.subject);
// Welcome, Alice!

Python SDK

preview_template.py

result = client.templates.preview(
    html="<h1>Hello {{firstName}}!</h1>",
    subject="Welcome, {{firstName}}!",
    variables={"firstName": "Alice"},
)
print(result["html"])    # <h1>Hello Alice!</h1>
print(result["subject"]) # Welcome, Alice!

Delete Template

DELETE /v1/templates/:id

delete-template.ts

await client.templates.delete('template_xxxxx');

Template Types

Templates can be categorized by type:

Type	Use Case
`transactional`	Order confirmations, password resets, receipts
`marketing`	Newsletters, promotions, announcements