---
title: Templates
description: Reusable email content for broadcasts, managed in the dashboard or with the API.
---

A template is reusable email content: a subject, HTML and an optional plain-text part. Keep one ready for your next [broadcast](/docs/concepts/broadcasts). In the dashboard, **Templates** lets you build one in the block editor or write the HTML yourself.

In the broadcast composer, choosing a template copies its content in as a starting point. Editing or deleting the template later does not change broadcasts you already made.

## Merge fields

Templates can carry per-contact values:

```html
<p>Hi {{{FIRST_NAME|there}}},</p>
```

- `{{{FIRST_NAME}}}`, `{{{LAST_NAME}}}` and `{{{EMAIL}}}` are built in. Any other name reads a [contact property](/docs/concepts/contacts) of that name.
- `{{{NAME|fallback}}}` uses the fallback text when the contact has no value.
- `{{{UNSUBSCRIBE_URL}}}` becomes each recipient's own unsubscribe link. See [Unsubscribes](/docs/concepts/unsubscribes).

## Block editor and HTML

- A template made in the block editor can be switched to HTML with **Edit as HTML**. You get a copy or change it in place. Until you save, **Back to blocks** restores the blocks.
- A template created with `html` through the API opens in HTML mode, and your HTML is kept exactly as written. Converting it to blocks is your choice, as a copy or in place, and it flattens table-based layouts.
- In HTML mode, a plain-text part generated from the HTML keeps following your edits. A plain-text part you set through the API is sent as stored.

## No drafts and no versions

Every save is live. A template has no draft or publish step and no version history. `status` always reads `published`, and `POST /templates/{id}/publish` does nothing and succeeds.

## API

The SDKs call the template endpoints as `templates.*`.

```bash
curl -X POST https://api.billionsend.com/templates \
  -H "Authorization: Bearer $BILLIONSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome",
    "subject": "Welcome to Acme",
    "html": "<p>Hi {{{FIRST_NAME|there}}}</p>",
    "alias": "welcome"
  }'
```

- `POST /templates` takes `name`, `html`, and optionally `subject`, `text` and `alias`.
- `GET /templates` lists templates, newest first. `GET /templates/{id}` returns the full content.
- `PATCH /templates/{id}` changes any of the fields. An empty string or `null` clears `subject` or `text`. Writing `html` or `text` turns a block-editor template into an HTML one.
- `DELETE /templates/{id}` deletes it.
- `POST /templates/{id}/duplicate` makes a copy named `<name> (copy)`, without the alias.

An `alias` is made of letters, digits, `.`, `_` and `-`, up to 100 characters, and is unique in your team. Every route above accepts the alias in place of the id. A taken alias answers `409`. An alias that looks like a UUID is not allowed.

## Not supported

- `from`, `reply_to` and `variables` on a template answer `422`. Set the sender and reply-to on the broadcast, and use merge fields directly: contact properties need no declaring.
- A template id cannot be sent with `POST /emails` or `POST /broadcasts`. Send `html` or `text` yourself. The broadcast composer's template picker copies the content in.
