Message templates API

REST endpoints for message templates in ServFlo: 7 operations with parameters, request and response fields, permissions and curl examples.

Base URL: https://app.servflo.ai/api. Every call needs Authorization: Bearer sfk_… (Authentication); {organizationId} ($ORGANIZATION_ID in the examples) is your business's id.

Operation	Endpoint	Risk
List message templates	`GET /organizations/{organizationId}/message-templates`	`read`
Create a message template	`POST /organizations/{organizationId}/message-templates`	`write`
List the merge fields	`GET /organizations/{organizationId}/message-templates/merge-fields`	`read`
Get a message template	`GET /organizations/{organizationId}/message-templates/{templateId}`	`read`
Edit a message template	`PATCH /organizations/{organizationId}/message-templates/{templateId}`	`write`
Delete a message template	`DELETE /organizations/{organizationId}/message-templates/{templateId}`	`sensitive`
Preview a message	`POST /organizations/{organizationId}/message-templates/preview`	`write`

List message templates

GET /organizations/{organizationId}/message-templates

Email and text templates, the presets' (system: editable, not deletable) first. Read-only.


Permission	`engagement.read` (Owner, Admin, Dispatcher)
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`messageTemplates_list` (toolset `marketing`)

Parameters

Name	In	Type	Required	Description
`channel`	query	enum	No	One of `EMAIL`, `SMS`.

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/message-templates" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

An array of objects:

Field	Type	Description
`id`	string
`name`	string
`description`	string or null
`channel`	enum	One of `EMAIL`, `SMS`.
`purpose`	enum	One of `TRANSACTIONAL`, `MARKETING`.
`subject`	string or null
`body`	string
`placeholders`	array of string
`variants`	array of object
`category`	string or null
`isSystem`	boolean
`systemKey`	string or null
`updatedAt`	string	ISO 8601 time (UTC).

Create a message template

POST /organizations/{organizationId}/message-templates

A reusable email or text. Nothing is sent: automations and the send dialogs use templates. Email needs a subject.


Permission	`engagement.manage` (Owner, Admin)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`messageTemplates_create` (toolset `marketing`)

Request body

Field	Type	Required	Description
`name`	string	Yes	Up to 200 characters.
`description`	string or null	No	Up to 1000 characters.
`channel`	enum	Yes	One of `EMAIL`, `SMS`.
`purpose`	enum	No	One of `TRANSACTIONAL`, `MARKETING`. Default `TRANSACTIONAL`.
`subject`	string or null	No	Email only; merge fields allowed. Up to 200 characters.
`body`	string	Yes	Text with {{merge.fields}} (GET /message-templates/merge-fields).
`variants`	array of object	No	A/B variants: { id, label, weight, subject?, body }. Up to 10 items. Default `[]`.
`variants[].id`	string	Yes	Up to 64 characters.
`variants[].label`	string	No	Up to 100 characters.
`variants[].weight`	integer	No	0–1000. Default `1`.
`variants[].subject`	string or null	No	Up to 200 characters.
`variants[].body`	string	Yes
`category`	string or null	No	Up to 40 characters.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/message-templates" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Dana Whitfield","channel":"EMAIL","body":"string"}'

Response

201: the answer's fields

Field	Type	Description
`id`	string
`name`	string
`description`	string or null
`channel`	enum	One of `EMAIL`, `SMS`.
`purpose`	enum	One of `TRANSACTIONAL`, `MARKETING`.
`subject`	string or null
`body`	string
`placeholders`	array of string
`variants`	array of object
`category`	string or null
`isSystem`	boolean
`systemKey`	string or null
`updatedAt`	string	ISO 8601 time (UTC).

List the merge fields

GET /organizations/{organizationId}/message-templates/merge-fields

Every {{merge.field}} a template can use (business, customer, property, job and visit, quote, invoice, payment, membership, links) with an example. Links are the real customer links, made when a message uses them. Read-only.


Permission	`engagement.read` (Owner, Admin, Dispatcher)
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`messageTemplates_mergeFields` (toolset `marketing`)

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/message-templates/merge-fields" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

An array of objects:

Field	Type	Description
`group`	string
`tags`	array of object
`tags[].token`	string
`tags[].label`	string
`tags[].help`	string
`tags[].example`	string

Get a message template

GET /organizations/{organizationId}/message-templates/{templateId}

One template with its subject, body, merge fields and A/B variants. Read-only.


Permission	`engagement.read` (Owner, Admin, Dispatcher)
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`messageTemplates_get` (toolset `marketing`)

Parameters

Name	In	Type	Required	Description
`templateId`	path	string	Yes	A message template id, from GET /message-templates.

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/message-templates/{templateId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`id`	string
`name`	string
`description`	string or null
`channel`	enum	One of `EMAIL`, `SMS`.
`purpose`	enum	One of `TRANSACTIONAL`, `MARKETING`.
`subject`	string or null
`body`	string
`placeholders`	array of string
`variants`	array of object
`category`	string or null
`isSystem`	boolean
`systemKey`	string or null
`updatedAt`	string	ISO 8601 time (UTC).

Edit a message template

PATCH /organizations/{organizationId}/message-templates/{templateId}

Replaces the template's name, subject, body and variants (the channel cannot change). Automations using it send the new text from their next message.


Permission	`engagement.manage` (Owner, Admin)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`messageTemplates_update` (toolset `marketing`)

Parameters

Name	In	Type	Required	Description
`templateId`	path	string	Yes	A message template id, from GET /message-templates.

Request body

Field	Type	Required	Description
`name`	string	Yes	Up to 200 characters.
`description`	string or null	No	Up to 1000 characters.
`channel`	enum	Yes	One of `EMAIL`, `SMS`.
`purpose`	enum	No	One of `TRANSACTIONAL`, `MARKETING`. Default `TRANSACTIONAL`.
`subject`	string or null	No	Email only; merge fields allowed. Up to 200 characters.
`body`	string	Yes	Text with {{merge.fields}} (GET /message-templates/merge-fields).
`variants`	array of object	No	A/B variants: { id, label, weight, subject?, body }. Up to 10 items. Default `[]`.
`variants[].id`	string	Yes	Up to 64 characters.
`variants[].label`	string	No	Up to 100 characters.
`variants[].weight`	integer	No	0–1000. Default `1`.
`variants[].subject`	string or null	No	Up to 200 characters.
`variants[].body`	string	Yes
`category`	string or null	No	Up to 40 characters.

Example

curl -X PATCH "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/message-templates/{templateId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Dana Whitfield","channel":"EMAIL","body":"string"}'

Response

200: the answer's fields

Field	Type	Description
`id`	string
`name`	string
`description`	string or null
`channel`	enum	One of `EMAIL`, `SMS`.
`purpose`	enum	One of `TRANSACTIONAL`, `MARKETING`.
`subject`	string or null
`body`	string
`placeholders`	array of string
`variants`	array of object
`category`	string or null
`isSystem`	boolean
`systemKey`	string or null
`updatedAt`	string	ISO 8601 time (UTC).

Delete a message template

DELETE /organizations/{organizationId}/message-templates/{templateId}

Destructive: deletes a template no automation uses (409 otherwise). Preset templates cannot be deleted.


Permission	`engagement.manage` (Owner, Admin)
Risk	`sensitive`, OAuth scope `servflo.sensitive`. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP tool	`messageTemplates_delete` (toolset `marketing`)
Approval	Over MCP, this tool always waits for your approval in ServFlo. See Approvals.

Parameters

Name	In	Type	Required	Description
`templateId`	path	string	Yes	A message template id, from GET /message-templates.

Example

curl -X DELETE "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/message-templates/{templateId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`ok`	true

Preview a message

POST /organizations/{organizationId}/message-templates/preview

Renders a subject and body (or a saved template) for a real customer and optional record, as it would be sent: merge fields filled, the branded email shell, the SMS length. Without a customer, the merge fields' examples are used. Nothing is sent.


Permission	`engagement.read` (Owner, Admin, Dispatcher)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`messageTemplates_preview` (toolset `marketing`)

Request body

Field	Type	Required	Description
`channel`	enum	Yes	One of `EMAIL`, `SMS`.
`purpose`	enum	No	One of `TRANSACTIONAL`, `MARKETING`. Default `TRANSACTIONAL`.
`subject`	string or null	No	Up to 200 characters.
`body`	string	No
`templateId`	string	No	Preview a saved template instead of subject/body.
`customerId`	string	No	The sample customer (GET /customers); examples when omitted.
`subjectType`	enum	No	One of `visit`, `job`, `quote`, `invoice`, `payment`, `membership`, `request`.
`subjectId`	string	No
`branding`	object	No	Email branding not saved yet (Settings → Messaging's live preview); without a customer only.
`branding.brandColor`	string or null	No	Up to 7 characters.
`branding.headerText`	string or null	No	Up to 120 characters.
`branding.footerText`	string or null	No	Up to 500 characters.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/message-templates/preview" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel":"EMAIL"}'

Response

200: the answer's fields

Field	Type	Description
`channel`	enum	One of `EMAIL`, `SMS`.
`subject`	string or null
`body`	string	The exact text (SMS) or the email's text part.
`html`	string or null	The branded email, as it would be sent.
`unresolved`	array of string	Merge fields with no value for this customer.
`warnings`	array of string
`sms`	object or null
`sms.characters`	integer
`sms.segments`	integer
`sms.encoding`	string

On this page