# Template versions

> Versions share an alias so you can draft, test and publish a new design without changing code. How publishing works in the dashboard and the API.

Versions let you change a template without touching the code that sends it. All versions of a template share one alias, and at most one of them is published. Sends by alias always use the published version, so you can draft a redesign, test it, and switch to it with one click.

## How versions work

Every template is a version with its own `tem_` ID, name, subject, From address, editor and content. Versions with the same alias form a group:

```text
welcome-email
├── Welcome email v3   tem_33W1rXk9Pd2LmQ7vB4nC8sTyFgh   Draft
├── Welcome email v2   tem_33Vd8Hq3Ws5NzK1xR7cM2pLbYte   Published   ← sends by alias use this one
└── Welcome email      tem_33TfB6yN4qJ8kV2mX9wR1cHsDua   Draft
```

| How you refer to the template | Which version is used |
| --- | --- |
| Alias, such as `"template": "welcome-email"` | The published version. If none is published, the send fails with `404 Template not found`. |
| `tem_` ID, such as `"template": "tem_33W1rXk9Pd2LmQ7vB4nC8sTyFgh"` | That exact version, published or not |

The same rules apply to the **Send email** step in [automations](/docs/automations/steps/). In the dashboard, the template list shows only the published version of each alias. Drafts appear in the **Versions** panel of the template page.

## Create a new version

1. **Open the template.** Go to **Email Marketing → Templates** and select the template.

2. **Start a version.** In the **Versions** panel, select **New Version**.

3. **Pick the source.** In the **Create New Version** dialog, choose the version to start from under **Copy from**, then select **Create Version**. Emailit copies its subject, From, Reply-To, editor and content into a new draft named after the source, such as `Welcome email v3`.

4. **Edit the draft.** Select **Open Editor** and make your changes. The published version keeps sending until you publish the draft.

A new version is also created whenever you add a template with an alias that already exists, whether with **Add template**, **Duplicate Template**, **Import**, or **Save as template** on a campaign. The new template is saved as a draft. The **Add template**, **Duplicate Template** and **Save as template** dialogs warn you with **Alias already exists**; **Import** doesn't.

## Test a draft

Send the draft to yourself by its `tem_` ID before you publish it. Copy the ID from the template page.

```bash
curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": "you@acme.com",
    "template": "tem_33W1rXk9Pd2LmQ7vB4nC8sTyFgh",
    "variables": { "first_name": "Ada", "plan": "Pro" }
  }'
```

## Publish a version

Publishing makes a version the live one for its alias. The version that was published before becomes a draft, so only one version is ever published.

**Dashboard**

  Open the draft and select **Publish**, or select the publish icon next to it in the **Versions** panel. The **Publish template** dialog warns that publishing will replace the current live version. Select **Publish** to confirm.

**API**

  Call [Publish a template](/docs/api-reference/templates/publish/) (`POST /templates/{id}/publish`) with the version's `tem_` ID and a **Full Access** key.

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/templates/tem_33W1rXk9Pd2LmQ7vB4nC8sTyFgh/publish \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**Node.js**

```javascript
const res = await fetch(
  'https://api.emailit.com/v2/templates/tem_33W1rXk9Pd2LmQ7vB4nC8sTyFgh/publish',
  { method: 'POST', headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` } },
);
const { data } = await res.json();
```

**Python**

```python
import os
import requests

res = requests.post(
    "https://api.emailit.com/v2/templates/tem_33W1rXk9Pd2LmQ7vB4nC8sTyFgh/publish",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
template = res.json()["data"]
```

**PHP**

```php
$ch = curl_init('https://api.emailit.com/v2/templates/tem_33W1rXk9Pd2LmQ7vB4nC8sTyFgh/publish');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('EMAILIT_API_KEY')],
]);
$template = json_decode(curl_exec($ch), true)['data'];
```

Publishing emits `template.updated` for the newly published version and for the version that was unpublished. To roll back, publish the previous version again.

## Edit or delete a published version

- **Edits are live immediately.** Saving changes to the published version changes what sends by alias use from that moment. The Dragit editor saves automatically as you work, so its changes go live as you make them. To stage changes, create a new version instead.
- **Deleting doesn't promote another version.** If you delete the published version, the alias has no published version, and sends and automations that use the alias fail until you publish another one. Deleting removes only that version; the others stay.

## Versions in the API

| Action | Behavior |
| --- | --- |
| [Create a template](/docs/api-reference/templates/create/) with a new alias | The template is published automatically. |
| [Create a template](/docs/api-reference/templates/create/) with an existing alias | The template is created as an unpublished version, with `published_at` set to `null`. |
| [List templates](/docs/api-reference/templates/list/) | Returns only published versions, one per alias, each with `total_versions`. |
| [Retrieve a template](/docs/api-reference/templates/get/) | Returns the version, plus `versions`: the alias's other versions with their `id`, `name`, `published_at`, `created_at` and `updated_at`, newest first. |
| [Update a template](/docs/api-reference/templates/update/) | Changes the version's fields without changing whether it's published. Changing the alias to one that's already in use fails with `Alias already exists`. |
| [Publish a template](/docs/api-reference/templates/publish/) | Publishes this version and unpublishes every other version of the alias. |
| [Delete a template](/docs/api-reference/templates/delete/) | Deletes only this version. |

## Related

- [Create and edit templates](/docs/templates/editors/)
- [Send with a template](/docs/email-api/send-email/#send-with-a-template)
- [Templates API reference](/docs/api-reference/templates/)

---
Source: https://emailit.com/docs/templates/versions/