Template Versions

Template versions let you create snapshots of your templates, control which version is active, and schedule version publishing. This enables safe iteration on templates while maintaining a stable production version.

How Versioning Works

Each template can have multiple versions:

Template: "order-confirmation"
├── Version 1 (created Jan 1)
├── Version 2 (created Jan 15)
└── Version 3 (active, created Feb 1)

Only one version can be active at a time. When you send emails using this template, the active version is used.

Viewing Versions

In the template editor:

Open a template
Click the Versions tab in the sidebar
View all versions with their status and creation dates

Each version shows:

Field	Description
Version number	Sequential version identifier
Status	Active, Inactive, or Scheduled
Created	When this version was created
Publish date	When the version will become active (if scheduled)

Creating a New Version

Create a version to snapshot your current template state:

Open the Template

Navigate to the template you want to version.

Access Versions

Click the Versions tab in the sidebar.

Create Version

Click Create Version and configure:

Active: Whether to immediately activate this version
Publish At: Optional date to automatically activate
Merge Tags: Required template variables for this version

When you create a version:

The current template content (HTML and JSON) is copied to the new version
The version number auto-increments
You can optionally activate it immediately or schedule it

Active vs Inactive Versions

Active Version

The active version is used when sending emails:

// This uses the active version
await lettr.emails.send({
  from: 'you@example.com',
  to: ['recipient@example.com'],
  subject: 'Your Order',
  template_slug: 'order-confirmation'
});

Only one version per template can be active. When you activate a version, the previously active version becomes inactive.

Using a Specific Version

Override the active version by specifying a version number:

// Use version 2 specifically
await lettr.emails.send({
  from: 'you@example.com',
  to: ['recipient@example.com'],
  subject: 'Your Order',
  template_slug: 'order-confirmation',
  template_version: 2
});

When no version is specified, Lettr always uses the active version. Use specific versions for testing or when you need to send an older version.

Scheduled Publishing

Schedule a version to become active at a future date:

Create or edit a version
Set the Publish At date and time
The version will automatically activate at that time

Use scheduled publishing to:

Plan template updates ahead of time
Coordinate template changes with marketing campaigns
Deploy changes during low-traffic periods

Version 3: Active now
Version 4: Scheduled to publish Jan 15 at 9:00 AM

When Version 4’s publish time arrives, it automatically becomes active and Version 3 becomes inactive.

Merge Tags (Template Variables)

Each version can define its required merge tags (template variables):

{
  "merge_tags": [
    { "key": "customer_name", "required": true },
    { "key": "order_id", "required": true },
    { "key": "order_total", "required": false }
  ]
}

Field	Description
`key`	Variable name as used in the template (e.g., `{{customer_name}}`)
`required`	Whether this variable must be provided when sending

Required merge tags must be included in substitution_data when sending. Sending without required variables will result in the variable placeholder appearing in the email.

Editor Type

Templates can be created with different editor types:

Editor Type	Description
`topol`	Created with the visual drag-and-drop Topol editor
`custom_html`	Created with custom HTML code

The editor type is stored per version, allowing you to switch between visual and code editing across versions.

Reverting to a Previous Version

To restore an older version:

Open the template’s Versions tab
Find the version you want to restore
Click Activate to make it the active version

This immediately makes the selected version active for all future sends.

Before making major changes, create a new version. This gives you a snapshot to revert to if needed.

Deleting Versions

You can delete inactive versions to clean up old iterations:

Open the template’s Versions tab
Find the version to delete
Click Delete

The delete option is disabled for the active version. Activate a different version first if you need to remove it.

Version Workflow

A typical versioning workflow:

Edit template (changes are auto-saved)
Test with preview and test emails
Create new version when ready to publish
Activate the new version (or schedule it)
Previous version remains available for rollback

Best Practices

Version before major changes: Create a version before redesigning a template
Use scheduled publishing: Schedule major changes for optimal timing
Keep a working version active: Always have a tested, stable version active
Document changes: Use version numbers to track what changed between versions
Clean up old versions: Delete versions you no longer need to keep the list manageable

Version Comparison

Compare versions by:

Opening a version’s preview
Opening another version’s preview in a new tab
Comparing the rendered output side-by-side

This helps verify changes before activating a new version.

API Usage

When using templates via API, version behavior follows these rules:

Scenario	Version Used
No version specified	Active version
`template_version: 2`	Version 2 (if exists)
Version doesn’t exist	Error returned
All versions inactive	Error returned (generic “template not found”)

// Get template details
const response = await fetch(
  'https://app.lettr.com/api/templates/order-confirmation',
  {
    headers: {
      'Authorization': 'Bearer lttr_xxxxxxxxxxxx'
    }
  }
);

const template = await response.json();
console.log(template.data.name); // "Order Confirmation"
console.log(template.data.slug); // "order-confirmation"

Templates Introduction

Get started with email templates

Template Language

Merge tags and dynamic content

Projects & Folders

Organize templates in projects

Template Editor

Design templates visually

Documentation

Quickstart

Learn

Integrations

Resources

Template Versions

How Versioning Works

Viewing Versions

Creating a New Version

Active vs Inactive Versions

Active Version

Using a Specific Version

Scheduled Publishing

Merge Tags (Template Variables)

Editor Type

Reverting to a Previous Version

Deleting Versions

Version Workflow

Best Practices

Version Comparison

API Usage

Templates Introduction

Template Language

Projects & Folders

Template Editor

​How Versioning Works

​Viewing Versions

​Creating a New Version

​Active vs Inactive Versions

​Active Version

​Using a Specific Version

​Scheduled Publishing

​Merge Tags (Template Variables)

​Editor Type

​Reverting to a Previous Version

​Deleting Versions

​Version Workflow

​Best Practices

​Version Comparison

​API Usage

​Related Topics

Templates Introduction

Template Language

Projects & Folders

Template Editor

How Versioning Works

Viewing Versions

Creating a New Version

Active vs Inactive Versions

Active Version

Using a Specific Version

Scheduled Publishing

Merge Tags (Template Variables)

Editor Type

Reverting to a Previous Version

Deleting Versions

Version Workflow

Best Practices

Version Comparison

API Usage

Related Topics