A template is a messagetemplate record. Its {{fields}} are filled at send time by Handlebars. What a field can name depends on what sends it, so ask where the template will be used before writing a single field. A field that names nothing prints as blank: there is no error.
Ask first
- Email or text? One template is one channel. The channel is fixed when the template is made.
- Where will it be sent from? An automation (which record starts it: a lead, a booking, a form), a broadcast to a customer group, or the Comm Center compose box.
- What should it say? The words, or what the AI should write. Which details of the person or record to include.
- From which address (email only). See Business email and the sending address: on the platform's email service it goes out from [email protected] under the business's name.
Steps
1. Message Templates: the template
find_records on messagetemplate by data.name first, so you don't make a second one. Then create_record:
| Field | Value |
|---|---|
name | letters, digits, -, _; 3–50 long; unique (a second one is refused 409 duplicate), e.g. booking-reminder |
deliveryType | email or sms (also whatsapp, push, notification) |
subject | email: the subject line, fields allowed |
html | email: the body |
text | SMS: the message. For email, an optional plain-text version. |
from | email, optional |
Which fields to use — by the place that sends it:
| Sent by | Fields that fill |
|---|---|
An automation step (send_email, send_sms, with templateIds) | {{data.<field>}} of the record that started the run, e.g. {{data.firstName}} on a lead. The same record also under its type: {{data.lead.firstName}}. Plus {{data.displayName}} (the business name), {{data.company.<field>}}, {{data.supportEmail}}, {{data.recordAdminLink}}. |
| A broadcast | {{firstName}}, {{lastName}}, {{name}}, {{email}}, {{phone}} of each recipient, and {{data.<field>}} of their record. {{unsubscribeUrl}} places the unsubscribe link; without it one is added at the bottom. |
| Comm Center compose | Nothing from the template is filled. Sending to a customer group or saved list fills {{firstName}}, {{lastName}}, {{name}}, {{email}}, {{phone}} only. |
Use only fields the record really has (get_schema on its datatype). There is no {{contact.…}} or {{customer.…}} in an automation run.
Helpers that work: {{uppercase x}}, {{lowercase x}}, {{capitalize x}}, {{titleCase x}}, {{currency x}} (US dollars; an empty value prints $0.00), {{dateFormat x}} (11/2/2026, or {{dateFormat x "full"}} for the long form), {{#if x}}…{{else}}…{{/if}}, {{#each list}}…{{/each}}, {{currentYear}}.
In html, a field's text is escaped (a <b> in a name shows as text). In subject and text it isn't.
For a text: keep it short. Over 160 plain characters (70 with emoji or accents) it goes as several parts, and each part is billed. Nothing warns or cuts it. Say who it's from in the first words. A marketing text needs "Reply STOP to opt out".
Hands on: the template's sk and name.
Check: open it (/message-template, then the template). The email editor's Visual tab shows a desktop and mobile preview. The text editor counts characters and parts.
2. Message Templates: preview against a real record
call_appengine POST /crm/test-template with:
{ "template": "<template name>", "sampleDatatype": "lead", "sampleId": "<a real lead's sk>" }It renders the template with that record and sends nothing. It answers subject, html, text and unresolved: every field that would print blank. Fix each one, or tell the person why it is empty (the record has no value). Instead of a record you can pass "data": { "firstName": "Ana" } to try values.
Use the sample the real sender will have: a lead for a lead automation, a reservation for a booking reminder. A broadcast's {{firstName}} doesn't resolve here, because this preview fills only {{data.…}}. That is expected.
Adding "send": true, "to": "<address>" sends the rendered template for real. Do it only to the person's own address, when they ask. The screen offers a test send for email only. Don't test-send a text template through the API: it sends a real, billed text.
Hands on: the preview, and the unresolved list (empty, or explained).
Check: the template's Test drawer on screen does the same with a sample record the person picks.
3. Automation or Broadcast: use it
- Automation: in the
send_emailorsend_smsstep,templateIds: ["<template sk>"](ortemplateNames: ["<name>"]), withto(e.g.{{data.email}},{{data.phone}}). See New-lead follow-up. The template's own channel decides how it goes: asend_smsstep with an email template sends an email. Match them. - Broadcast: set the email broadcast's
emailConfig.templateId(ortemplateId) to the template's sk or name. A name that matches no template stops the send withtemplate_not_found. The template fills only what the broadcast leaves empty (subject, body). See Email campaign draft.
Stop: an automation or broadcast that uses the template reaches real people. Build it as a draft and follow that skill's own Stop.
Hands on: where the template is used. Check: the step or broadcast shows the template by name.
When it's done
Tell the person:
- the template's name and channel;
- the fields it fills, and where it must be sent from for them to fill;
- the preview's result, and any field that will print blank;
- where it is used, and that nothing has been sent.
Open the template on Message Templates.
What it can't do yet
- Blank, not an error. A field that names nothing prints as nothing, everywhere except
POST /crm/send-template, which refuses withUNRESOLVED_PLACEHOLDERS. Preview every template. - Comm Center doesn't fill template fields. The compose box's Personalize button and its template picker put
{{data.…}}into the message, and they go out as typed. Use a broadcast for personalised sends. - The inbox reply box's templates are samples. Its "Welcome Message" and "Follow Up" are built in and not your templates.
- A broadcast ignores the template's plain-text version. The text part is made from the HTML.
- "Default" does nothing. A template's
isDefaultis saved but not used to pick it. - A channel can't be changed. To turn an email into a text, make a new SMS template. Changing
deliveryTypeon a saved one leaves the email's HTML as the text.
Don'ts
- Don't write
{{lead.name}},{{contact.email}}or{{customer.firstName}}. Use the fields of the place that sends it (the table in step 1). - Don't use single braces (
{name}). Only{{…}}is filled. - Don't test-send to customers. The preview sends nothing; use it.
- Don't promise prices, dates or offers in a template the person didn't give you.