Create and retrieve email template setup details

POST /api/communications/email-template-setup

Success: 200 OK

Products: Operator (FOH)
Features: Front of House Generic Access (FOHGENERIC)

Overview

Creates an email template and returns everything an editor needs to render it: the new template's identifier, its HTML, its editor configuration and the list of merge placeholders available to it.

Despite reading like a lookup, this call writes. Every request inserts a new, disabled email template record and returns its templateId; send it twice and you have two templates. Send it once when a user starts a new template, keep the templateId you get back, then use Retrieve email template setup details for editing for every subsequent load of that same template.

A template is always created against two things: a query — a saved audience definition that both selects the recipients and supplies the data merged into the message — and a template type, which supplies the new template's name. The placeholder list in the response is derived from the fields of that query at request time; it is not stored with the template.

Endpoint

POST {base_url}/api/communications/email-template-setup

{base_url} is the environment URL issued to your integration. See Authenticating with Gladstone APIs.

Request body

Field	Type	Required	Description
`queryId`	integer (int32)	Yes	The saved communication query (audience definition) the template is built against. Its fields determine the `placeholders` returned, and its description becomes the response `description`. Must be a positive integer — `0` or lower is rejected with `QueryId must be a positive number` — and the query must already exist, or the call fails with `404`. Required together with `templateTypeId`.
`templateTypeId`	integer (int32)	Yes	The email template type the new template is based on; its stored description becomes the template's name. Must be a positive integer — `0` or lower is rejected with `TemplateTypeId must be a positive number` — and must match an existing template type, or the call fails with `404`. Required together with `queryId`.

Sample request

cURL

curl -X POST '{base_url}/api/communications/email-template-setup' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true' \
  -H 'Content-Type: application/json' \
  -d '{
  "queryId": 12345,
  "templateTypeId": 12345
}'

Response fields

Field	Type	Description
`closeDelimiter`	string	The marker that closes a placeholder inside `html`. Always `]]` — it never varies.
`config`	string	The editor configuration JSON saved alongside a template's HTML. Always `null` here, because the template has just been created and has no saved content yet.
`description`	string	The description of the query the template was created against, copied at creation time.
`openDelimiter`	string	The marker that opens a placeholder inside `html`. Always `[[` — so a placeholder is written `[[PlaceholderName]]`.
`placeholders`	string	The merge fields available to this template, as one comma-separated string of `Label:Placeholder` pairs — show the label to a user, write the second half between the delimiters. Built from the fields the query reads, plus the tenant's custom fields. If the query is written as raw SQL rather than with the query builder, the names of the fields it returns are appended as `name:name` pairs; if the query does have builder filters, none are added.
`templateId`	string	The identifier of the template this call has just created, as a string. Store it — it is the only handle on the new template, and you supply it to Retrieve email template setup details for editing.
`queryId`	string	The query the template is now bound to, echoed back as a string.
`templateName`	string	The new template's name, taken from the description of the template type you sent.
`templateTypeId`	string	The template type the template was created from, echoed back as a string.
`html`	string	The template's saved HTML body. Always an empty string here — a template created by this call has no content until content is saved against it.
`previewOnly`	boolean	Part of the editor payload contract; this endpoint never sets it, so it is always `false`. Nothing you send changes it.

Sample response

200 OK

{
  "closeDelimiter": "string",
  "config": null,
  "description": "string",
  "openDelimiter": "string",
  "placeholders": "string",
  "templateId": "string",
  "queryId": "string",
  "templateName": "string",
  "templateTypeId": "string",
  "html": "",
  "previewOnly": false
}

Errors

Status	Meaning	When
`400`	Bad request	`queryId` or `templateTypeId` is absent or not positive — `QueryId must be specified`, `QueryId must be a positive number`, `TemplateTypeId must be specified`, `TemplateTypeId must be a positive number`.
`404`	Not found	The query does not exist (`Query with id {queryId} does not exist.`) or the template type does not exist (`Email template type with id {templateTypeId} doesn't exist.`).
`500`	Internal server error	An unexpected failure while reading the query or building the placeholder list. Note that the template is created before those steps, so a `500` can leave a template behind with no content.

This page as markdown · All pages · llms.txt