Skip to main content
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:
  1. Open a template
  2. Click the Versions tab in the sidebar
  3. View all versions with their status and creation dates
Each version shows:
FieldDescription
Version numberSequential version identifier
StatusActive, Inactive, or Scheduled
CreatedWhen this version was created
Publish dateWhen the version will become active (if scheduled)

​
Creating a New Version

Create a version to snapshot your current template state:
1

Open the Template

Navigate to the template you want to version.
2

Access Versions

Click the Versions tab in the sidebar.
3

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:
  1. Create or edit a version
  2. Set the Publish At date and time
  3. 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 }
  ]
}
FieldDescription
keyVariable name as used in the template (e.g., {{customer_name}})
requiredWhether 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 TypeDescription
topolCreated with the visual drag-and-drop Topol editor
custom_htmlCreated 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:
  1. Open the template’s Versions tab
  2. Find the version you want to restore
  3. 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:
  1. Open the template’s Versions tab
  2. Find the version to delete
  3. 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: 
1. Edit template (changes are auto-saved)
2. Test with preview and test emails
3. Create new version when ready to publish
4. Activate the new version (or schedule it)
5. Previous version remains available for rollback

​
Best Practices

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

​
Version Comparison

Compare versions by:
  1. Opening a version’s preview
  2. Opening another version’s preview in a new tab
  3. 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:
ScenarioVersion Used
No version specifiedActive version
template_version: 2Version 2 (if exists)
Version doesn’t existError returned
All versions inactiveError 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