POST/api/v1/projects/{project_id}/templates/{template_id}/preview

Needs scope: readIdempotency-Key MCP tool: preview_template operationId preview_template

Preview a message template

Renders the template’s latest version, with the latest versions of the partials it includes, as a subscriber would get it: the subscriber subscriber_id’s email, attributes and list name, or sample_attributes, or, with neither, sample values. The unsubscribe and confirmation links are samples (https://postwind.invalid/...); campaign.name is Sample campaign. The text is the text body, or the HTML made into text; when the project’s auto_footer is true, the footer with the unsubscribe link is added to each that does not show {{ unsubscribe_url }}. Nothing is written. Needs scope read.

Parameters

Name	In	Type	Description
`project_id`required	path	string · uuid	The project’s id
`template_id`required	path	string · uuid	The message template’s id
`Idempotency-Key`	header	string 1–128 characters · pattern `^[!-~]{1,128}$`	A key of the client’s choosing, one per request it means to send once (a UUID will do). A repeat with the same key and the same body within 24 h creates nothing again and gets the first answer, marked `Idempotent-Replayed: true`. The key belongs to the API key that sent it. Only a `2xx` answer is kept: after any other answer the key is free again.

Request body

application/json · required

PreviewTemplateRequest object
sample_attributesobject | null

Attributes to render with, as a subscriber’s: string, number or boolean values, up to 64 keys, up to 4 KB of JSON; any other attribute the template names is undefined. Not with subscriber_id; null or left out: none.
subscriber_idstring · uuid | null

A subscriber of the project: its email, attributes and list name. Not with sample_attributes; null or left out: none.

Responses

200

The rendered message

Header	Type	Description
`Idempotent-Replayed`	string · enum	`true` when the answer is a replay of an earlier request with the same `Idempotency-Key`; absent otherwise.

TemplatePreview object · all fields required
htmlstring

The HTML part, with the automatic footer when it was added.
subjectstring
textstring

The text part: the text body, or the HTML made into text; with the automatic footer when it was added.
warningsarray of PreviewWarning
3 fields
- PreviewWarning object · all fields required
- codestring
  
  subscriber_not_active, subscriber_list_deleted, empty_subject, html_too_large, auto_footer_added, text_from_html.
  
  example auto_footer_added
- messagestring
- partPreviewPart | null
  
  The part it is about; null: the message as a whole.
  - subject
  - html
  - text

400

Not JSON (invalid_json)

Problem (application/problem+json)

401

No valid key

Problem (application/problem+json)

403

A project key without scope read (forbidden)

Problem (application/problem+json)

404

No such project, template or subscriber in it, or another project’s (not_found)

Problem (application/problem+json)

409

A request with the same Idempotency-Key has not answered yet (idempotency_key_in_progress)

Problem (application/problem+json)

413

Over 10 MB (body_too_large)

Problem (application/problem+json)

415

Not application/json (unsupported_media_type)

Problem (application/problem+json)

422

Invalid fields, every one in errors (validation_failed): both subscriber_id and sample_attributes, invalid attributes, a partial (template_id), or the template does not render with this data, with the codes of saving; or the Idempotency-Key was used in the last 24 h for another request (idempotency_key_reused), or is not 1 to 128 visible ASCII characters (validation_failed, field Idempotency-Key)

Problem (application/problem+json)

429

The key is over its rate limit, api.rate_limit_per_minute requests a minute on this node (rate_limited)

Header	Type	Description
`Retry-After`	integer	Seconds until the key’s next request passes; rounded up.

Problem (application/problem+json)

504

Postwind’s storage did not answer within its time limit (storage_timeout). A change the request makes may still take effect: check before repeating it. A repeat with the same Idempotency-Key never runs it twice: it is 409 idempotency_key_in_progress until the key’s 24 h end

Problem (application/problem+json)

bashRequest

# set POSTWIND_URL, POSTWIND_KEY and the ids first
curl -X POST "$POSTWIND_URL/api/v1/projects/$PROJECT_ID/templates/$TEMPLATE_ID/preview" \
  -H "Authorization: Bearer $POSTWIND_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data @- <<'JSON'
{}
JSON

MCP tool `preview_template`

Call it: to check the layout and the variables of a template, for one subscriber (subscriber_id: its email, attributes and list name) or with sample_attributes (not both; with neither, every attribute is the text sample). The latest version of the template and of each partial it includes is rendered; the unsubscribe links are samples (https://postwind.invalid/...) and campaign.name is Sample campaign. A template without a text body gets its text made from the HTML; when the project’s auto_footer is true, a part that does not show {{ unsubscribe_url }} gets the footer with the unsubscribe link.
Needs: an admin key with project_id, or a project key with scope read (its own project; the argument is ignored), and a message template: a partial is validation_failed on template_id; a subscriber of another project is not_found; a template that does not render with this data is validation_failed with the errors of saving. Nothing is written.
Returns: subject, html, text and warnings (code, part, message), the same as POST /api/v1/projects/{project_id}/templates/{template_id}/preview.

jsontools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "preview_template",
    "arguments": {
      "template_id": "<template_id>"
    }
  }
}

Open the tool page