# 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`)

HTML version: [Create and retrieve email template setup details](https://support.gladstonesoftware.cloud/reference/communications/create-and-retrieve-email-template-setup-details)

## 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](retrieve-email-template-setup-details-for-editing.md) 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](../../guides/authenticating-with-gladstone-apis.md).

## 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

```bash title="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](retrieve-email-template-setup-details-for-editing.md). |
| `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

```json title="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. |