POST/templates

POST /templates

Create a new template.

Request

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

Required scopes

The key must carry these:

templates:write

Body parameters

Name	Type	Required	Description
name	string	Yes	Template name.
subject	string	Yes	Subject line. Supports Handlebars variables.
previewText	string	No	Preview text: the line inboxes show after the subject, sent as a hidden preheader at the top of the body. Supports Handlebars variables. Whitespace collapses to one line and blank means none. At most 200 characters (`templates.previewTextTooLong`).
bodyHtml	string	No	HTML body, for a raw-HTML template. Supports Handlebars variables. Send exactly one of `bodyHtml` or `document`.
document	object	No	Block document, for a builder template. The server validates it and compiles `bodyHtml` from it. A block carries its props at the TOP LEVEL, not under a `props` key: `{"id": "b1", "type": "heading", "text": "Hi", "level": 1}`. Send exactly one of `bodyHtml` or `document`.
bodyMjml	string	No	MJML source.
emailType	MARKETING \| TRANSACTIONAL	Yes	Required, with no default. The type decides how every future send of this template behaves, so the API asks for intent rather than guessing it.
tagIds	uuid[]	No	Tags to attach.

emailType is required here and has no default, because either guess is wrong for someone: a password-reset template treated as marketing would be suppressed for contacts who unsubscribed and would gain an unsubscribe footer. Declare the type. A template is either raw HTML or blocks, never both. Sending both bodyHtml and document is refused rather than one of them silently winning. On a block template the server compiles bodyHtml from the document, so the HTML is always exactly what the blocks say, which is also why a direct bodyHtml edit on a block template is refused until you eject. Block props sit at the top level of a block and there is no props wrapper: it is the first mistake nearly everyone makes. If you are generating documents programmatically, check them with POST /templates/validate before saving, and see the templates page for the block types. Each type's required fields are enforced server-side, and validate names the ones you missed. Separately, in a marketing template {{unsubscribe_url}} puts the opt-out link where you want it: if the rendered email contains no anchor tag at all, a default unsubscribe footer is appended, and the word unsubscribe as plain text does not count as a link. The template engine is Handlebars, and the built-in helpers all work: {{#if}}, {{else}}, {{#each}} (nesting included), {{this}}, {{@index}}, {{#unless}}, {{#with}} and {{lookup}}. Five Liquid-style pipe filters are converted automatically, so {{ name | upcase }} works: prepend, append, default, upcase and downcase. {{var}} HTML-escapes its value and {{{var}}} is the raw form. A variable that is referenced but missing renders as an empty string, and a template that fails to compile fails the send, and the preview, with a 400 templates.renderFailed.

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.
400: emailType was omitted. It is required and has no default.
400: templates.previewTextTooLong: previewText is longer than 200 characters. Merge tags count as written, before they are filled in.

Rate limits

100/min per key, counted against the organization's WRITE ceiling (400/min). Both windows are one minute.