PATCH/templates/{id}

PATCH /templates/{id}

Update an existing template. Only the fields you send are changed.

Request

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

Required scopes

The key must carry these:

templates:write

Path parameters

Name	Type	Required	Description
id	uuid	Yes	Template UUID.

Body parameters

Name	Type	Required	Description
name	string	No	Template name.
subject	string	No	Subject line.
previewText	string \| null	No	Preview text, the line inboxes show after the subject. Omit to keep it; `null` or an empty string removes it. At most 200 characters.
bodyHtml	string	No	HTML body. On a block template this is refused until you eject with `document: null`, because the server owns that HTML.
document	object \| null	No	An object recompiles the template from those blocks. An explicit `null` ejects to raw HTML. Omitting the field leaves the authoring mode alone. See the note below: `null` and omitted are different requests.
bodyMjml	string	No	MJML source.
emailType	MARKETING \| TRANSACTIONAL	No	Reclassify the template. Changing the value requires `confirmEmailTypeChange: true` in the same request. See the create endpoint for what the classification changes.
confirmEmailTypeChange	boolean	No	Required whenever `emailType` actually changes. Reclassifying is a compliance event: `TRANSACTIONAL` to `MARKETING` makes future sends consent-suppressible, and the reverse strips the unsubscribe machinery, so a type change without this flag is refused rather than applied as a silent side effect of an edit.
tagIds	uuid[]	No	Replaces the template's tags.

document has three states and two of them look alike. An object recompiles from those blocks. An explicit null ejects to raw HTML: the document is dropped and the last compiled bodyHtml becomes editable by hand, one way, with no route back to blocks. Omitting the field changes the mode not at all. So a client that strips null fields before serialising can never eject, which is worth checking in your HTTP layer before you conclude the endpoint is broken. Everything else here is a genuine partial update: a PATCH touches only the fields it sends.

Responses

Returns 200 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: templates.emailTypeChangeNeedsConfirmation: emailType changed without confirmEmailTypeChange: true.
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.