Templates
A template is the words of one message: a subject and a body for an email, or just a body for a text. Automations send templates, and a template never sends anything on its own. This page shows you how to write one, and how to use merge fields to fill in the client's name, the property address, and the rest.
What a key sees
The API reads and writes the same Pulse library brokers see in BrokerPlus. A key sees the templates
of every team its broker belongs to, and a new template goes to the team the broker is working in.
Creating, changing, or archiving one needs permission to change automations; without it the API
returns 403 AUTOMATION_MANAGE_FORBIDDEN.
Two kinds of template aren't in the API: task templates (they describe a task an automation files, not a message), and the follow-up copy of a named outreach variant, which is edited beside its variant in BrokerPlus.
attachments lists the files sent with each email from a template, with their name, size, and type.
Add or remove attachments in BrokerPlus.
Find the merge fields
A merge field drops a value from the file into the message, such as the client's first name.
GET /v1/templates/merge-fields lists every one, including your brokerage's custom fields.
Code
The list is long. These are the fields a stage-change email usually needs:
| Merge field | Value |
|---|---|
client.firstName, client.fullName | The client the message goes to. |
partner.realtor.fullName, partner.realtor.email, partner.realtor.phone | The Realtor on the deal. |
property.fullAddress | The address of the subject property. |
deal.financingConditionDate | The financing condition date. |
broker.fullName, broker.email, broker.phone, broker.signature | The broker the message goes out as. |
available_on tells you which automations can fill a field. A deal field is empty in an
automation that runs on a contact with no deal, so keep deal fields out of contact automations.
Write a merge field
Write a merge field between double braces: {{client.firstName}}. A bare merge field is required:
if the file has no value for it, BrokerPlus holds the message for the broker rather than send it with
a gap.
When the value can be missing, add a fallback after a vertical bar:
{{partner.realtor.firstName|your Realtor}}. Give every field whose may_be_empty is true a
fallback.
A merge field that isn't in the list is refused with 400 UNKNOWN_MERGE_FIELDS, and
error.details.unknown names each one.
Create a template
POST /v1/templates creates a template. An email template needs a subject. A text template has
neither subject nor body_html, and sending either one is refused.
Code
To send it, name the template's id in an email or sms step of an
automation.
Change a template
PATCH /v1/templates/{id} changes the fields you send. Every automation that sends the template uses
the new words from its next message on.
body_html is the formatted version of an email. If you send a new body without a new body_html,
BrokerPlus drops the formatted version, because it still holds the old words. Send both to keep a
formatted email. Scripts and unsafe markup are stripped from body_html before it is saved.
A template's channel can't change. Create a new template instead.
Archive a template
DELETE /v1/templates/{id} archives the template. Messages it already sent stay on the file. If an
automation still sends it, the API returns 409 TEMPLATE_IN_USE: take it out of that automation
first, with PATCH /v1/automations/{id} or in BrokerPlus.
GET /v1/templates leaves archived templates out. Add include_archived=true to see them.
Outreach templates
Outreach templates are the first message a broker sends by hand from the refinance, renewal, and
lead lanes, as the outreach templates editor shows them. They are separate from the Pulse library
above: automations never send them. kind names the lane and the channel: refinance_initial,
renewal_initial, and leads_initial are emails, and refinance_sms, renewal_sms, and
leads_sms are texts.
Each broker keeps their own set, and their team keeps a shared set. GET /v1/outreach-templates
lists both; scope says which set a template is in. A teammate's own templates are never listed.
The first time a lane is listed, the broker's own set gets the default copy, as in the editor.
POST /v1/outreach-templatesadds one to the broker's own set, or to the team's with"scope": "team". Send nosubjectand nobodyto start from the lane's default copy.PATCHandDELETE /v1/outreach-templates/{id}change or remove one. The broker's own set always keeps one template per lane.body_htmlis the formatted version of an email template, as the broker's editor saves it. Send it onPATCHwithbodyas the plain-text version of the same message. A newbodywithout a newbody_htmlremoves the formatted version, and null goes back to plain text. Scripts and unsafe markup are stripped before it is saved, and a text template never keeps one.POST /v1/outreach-templates/{id}/set-primarymakes it the one the lane starts from when the broker sends. Each set has one primary per lane.POST /v1/outreach-templates/{id}/duplicatecopies it in its own set,/sharecopies one of the broker's own into the team's set, and/copy-to-personalcopies one of the team's into the broker's own.
Only a broker who can send email can write the team's set; anyone else gets 403. Nothing here
sends a message.
Media library
The media library holds the pictures and video stills the brokerage puts in outreach emails. Every broker in the brokerage shares one library.
GET /v1/media-assetslists it, newest first.urlis the picture's permanent public address, the one an email shows.POST /v1/media-assetsuploads a picture: PNG, JPEG, WebP, or GIF, at most 10 MB and 2000 pixels on its longest side. Send JSON withfile_nameandcontent_base64, ormultipart/form-datawith the file in a field namedfile.POST /v1/media-assets/video-linksadds a YouTube, Vimeo, Loom, NeetoRecord, Instagram, or Facebook video as a still with a play button, linking to the video.DELETE /v1/media-assets/{id}removes one. An email already sent that shows it shows a broken picture from then on.
Code