POST/templates/preview

POST /templates/preview

Render unsaved HTML or a block document exactly as a send would compose it, without saving a template.

Request

curl -X POST 'https://api.sendheron.com/api/v1/templates/preview' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json'

Required scopes

The key must carry these:

templates:read

Body parameters

Name	Type	Required	Description
bodyHtml	string	No	Raw HTML to preview. Send exactly one of `bodyHtml` or `document`.
document	object	No	Block document to compile and preview. Send exactly one of `bodyHtml` or `document`.
emailType	MARKETING \| TRANSACTIONAL	No	Which type to preview as, which decides whether an unsubscribe is owed. Omitting it previews as marketing: an unknown type never weakens compliance.
channel	CAMPAIGN \| BULK \| SEQUENCE \| DIRECT \| TRANSACTIONAL_API	No	Which channel to preview through. A channel can only tighten the policy, never loosen it. Defaults to `DIRECT`.
sampleData	object	No	Values for the Handlebars variables, so the preview renders real-looking content instead of empty placeholders.

This is here to show you what you did not write. The preview composes through the same path a real send uses, so it includes the unsubscribe block marketing mail gains and the effect of the channel floor: preview a TRANSACTIONAL template with channel: CAMPAIGN and the unsubscribe still appears, because CAMPAIGN and BULK are always marketing whatever the template says. Neither of those is something a client-side renderer can show you, which is the argument for previewing here instead of rendering blocks in your own UI. The response carries the composed renderedHtml alongside four authoring flags, so you can tell what the pipeline did rather than diffing HTML to find out: injectedUnsubscribeFooter, hasUnrecognizedUnsubscribeLink, appendedPromoBadge, and unsubscribeVariableIgnored. That last one is the one to watch when porting a template in from another provider: it means the template references {{unsubscribe_url}} but its policy never supplies that variable, so a real send renders the link empty. Link click tracking is the one send-time step a preview does not apply.

Responses

Returns 201 on success.

400: The payload failed validation, or the request is not valid for the current state. The body's `description` names the field and says what was wrong with it in words, e.g. "domain: domain must be a bare hostname such as acme.com, with no scheme, path, or port". The `error` code is stable and safe to branch on; `description` is for the human reading the log.
401: Missing or invalid API key.
403: Valid key, but it does not carry the required scope. The `error` code is `apiKeys.insufficientScopes` and the `description` names both halves of the problem: "Missing required scope(s): X. This key holds: Y." Neither is a secret, since the required scopes are on this page and the held ones are your own credential, and a bare "Forbidden" costs a debugging pass to work out which of the two it was.
404: No such record in this workspace. An id belonging to a different workspace returns this too, never a 403, because the API will not confirm that a record exists outside the workspace your key was issued in. Read it as "not yours or not there" rather than as "definitely gone".
409: A duplicate, or an idempotency key reused with a different payload.
429: Either rate-limit ceiling was exceeded.
400: Neither or both of `bodyHtml` and `document` were supplied. A `null` or blank `bodyHtml` counts as absent, matching the save path.
400: `templates.renderFailed`: the body failed to compile as a Handlebars template. The preview fails exactly as the send would.

Rate limits

100/min per key, counted against the organization's READ ceiling (1200/min). Both windows are one minute. There is no hourly or daily quota.