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.
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. It used to default to MARKETING, which was the safe direction for promotional mail and the dangerous one for authentication mail: a password-reset template created without the field became consent-suppressible and gained an unsubscribe footer, and nothing said so. 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 used to default to `MARKETING` and no longer does.

Rate limits

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