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.

Saving vs. Publishing

This is the most important thing to understand about versions: saving a template does not change what your application sends.

Action	What happens
Save in the editor	Creates a new version that is inactive (a draft). Nothing changes for emails sent through the API.
Publish a version	Makes that version active. From now on, sends by template slug use it. The previously active version becomes inactive.

So after editing a template there are always two steps: save, then publish. If you add a button, save, and then trigger an email from your application, the email still comes from the previously published version — the new button is missing until you publish the version that contains it.

A change that shows up in the editor and in the editor’s preview but is missing from the email your application sent is almost always an unpublished version. Open the template, click See versions, and check which version is marked active.

The template detail page tells you which state you are looking at: the header reads “This version is currently Active in production” or “This version is not active in production”.

Templates created or updated through the Template API behave differently: an API update publishes the new version immediately.

Viewing Versions

On the template detail page:

Open a template
Click See versions to open the Version History panel
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

You don’t create versions by hand — every time you click Save in the editor, Lettr snapshots the template as a new version:

The current template content (HTML and JSON) is copied to the new version
The version number auto-increments
The merge tags used in the content are detected and stored with the version
The new version is inactive until you publish it

Publishing a Version

Open the Template

Navigate to the template’s detail page.

Open Version History

Click See versions.

Publish

Open the menu (⋯) on the version you want to go live and choose Publish. In the Publish Version dialog, leave the date empty to publish immediately, or pick a date and time to schedule it.

The same menu lets you Compare a version with another, Show email to preview it, and Delete inactive versions.

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:

Click See versions and choose Publish on the version
Pick a date and time in the Publish Version dialog
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

Include every merge tag the template uses in substitution_data when sending. A merge tag with no matching value renders as empty text — the email is still sent, with a blank where the value should be (or a link with an empty address). Names are case-sensitive, so customer_name does not fill {{CUSTOMER_NAME}}.

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 and click See versions
Find the version you want to restore
Open its menu and choose Publish to make it the active version

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

Because every save creates a version and the published one stays active, you can iterate freely: nothing you save reaches recipients until you publish it, and the previous version is always there to roll back to.

Deleting Versions

You can delete inactive versions to clean up old iterations:

Open the template and click See versions
Find the version to delete
Open its menu and choose Delete

The delete option is not offered for the active version. Publish a different version first if you need to remove it.

Version Workflow

A typical versioning workflow:

Edit the template and click Save (creates a new inactive version)
Test with the editor preview and test emails
Open See versions and Publish the new version (or schedule it)
Send through the API — the published version is now used
Previous version remains available for rollback

To test an unpublished version through the API before it goes live, pass its number as template_version — see Using a Specific Version.

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

Saving vs. Publishing

Viewing Versions

Creating a New Version

Publishing a 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

​Saving vs. Publishing

​Viewing Versions

​Creating a New Version

​Publishing a 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

Saving vs. Publishing

Viewing Versions

Creating a New Version

Publishing a 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