Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

Templates

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. 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:

<p>Hi {{{FIRST_NAME|there}}},</p>
  • {{{FIRST_NAME}}}, {{{LAST_NAME}}} and {{{EMAIL}}} are built in. Any other name reads a contact property 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.

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.*.

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.

Was this page helpful?