> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lettr.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Template Versions
> Create template version snapshots in Lettr, control which version is active, and schedule publishing for safe iteration on live emails.
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:
| 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:
Navigate to the template you want to version.
Click the **Versions** tab in the sidebar.
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:
```javascript theme={null}
// 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:
```javascript theme={null}
// 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):
```json theme={null}
{
"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:
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:
| 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") |
```javascript theme={null}
// 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"
```
## Related Topics
Get started with email templates
Merge tags and dynamic content
Organize templates in projects
Design templates visually