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)
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
- 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'
});
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
{
"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 |
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:
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
- 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"
