docs
/
AI skills

Email and SMS templates with merge fields

Write a reusable email or text message template whose {{fields}} fill in from the customer, lead or booking it is sent about, preview it against a real record, and use it from an automation or a broadcast. Nothing is sent while building it.

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:

FieldValue
nameletters, digits, -, _; 3–50 long; unique (a second one is refused 409 duplicate), e.g. booking-reminder
deliveryTypeemail or sms (also whatsapp, push, notification)
subjectemail: the subject line, fields allowed
htmlemail: the body
textSMS: the message. For email, an optional plain-text version.
fromemail, optional

Which fields to use — by the place that sends it:

Sent byFields 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 composeNothing 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_email or send_sms step, templateIds: ["<template sk>"] (or templateNames: ["<name>"]), with to (e.g. {{data.email}}, {{data.phone}}). See New-lead follow-up. The template's own channel decides how it goes: a send_sms step with an email template sends an email. Match them.
  • Broadcast: set the email broadcast's emailConfig.templateId (or templateId) to the template's sk or name. A name that matches no template stops the send with template_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 with UNRESOLVED_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 isDefault is 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 deliveryType on 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.