Skip to content

Set an email-template override

PUT
/email-templates/{template}/{part}

Saves a replacement for one part of an email template.

You need system.config.write or system.admin for the whole install; read permission isn’t enough, and a permission held only for a team doesn’t count. A body that can’t be decoded gets a plain-text 400, even when you aren’t signed in. Otherwise signed-out callers get 401 and callers without the permission 403.

The server trims the template name and part, then matches them case-sensitively. The template must be registered, and part must be subject, text or html and exist on that template. body must be nonempty and at most 65,536 UTF-8 bytes. Whitespace-only text is accepted; an omitted or null body counts as empty and gets 400. Once the body length checks pass, an unknown name or unavailable part gets 404.

Subject and text parts use Go text/template, and HTML uses html/template. Before saving, the server parses the source and runs it against one sample with missingkey=error. In that sample numbers are 2 and each repeated group has one row. A parse or execution error gets 422, and a missing-key error names the key. Only branches that sample reaches are checked, so a successful save doesn’t prove every future value, branch or group size will render.

When an email is rendered, each part prefers its saved override. If there’s no override, the lookup fails, or the override fails to parse or execute, the shipped part is used. Real sends don’t use the strict missing-key setting, so a missing value doesn’t necessarily trigger the fallback. Values inserted into HTML are escaped for their context, but literal HTML written into the template isn’t sanitized by this endpoint.

The response is the saved source row. Other parts and templates are untouched. Cache invalidation across instances is best-effort, and a render already in progress can use an older copy. There’s no version check or transaction covering several part updates, and concurrent saves to the same part can overwrite each other. Saving doesn’t send a test email.

template
required
string

The registered template name, for example admin_test. Surrounding whitespace is trimmed; matching is case-sensitive.

part
required
string

The part to replace: subject, text or html. The named template must ship it. Surrounding whitespace is trimmed.

Replacement source for the template and part in the request path.

object
body
required

Nonempty template source, up to 65,536 UTF-8 bytes. Subject and text use Go text/template, and HTML uses html/template. The source must parse and run against the event’s one validation sample with missingkey=error. Passing that check doesn’t cover every future branch or value. An omitted or null body counts as empty and is rejected.

string
>= 1 characters

The saved source override and its update timestamp when available.

One saved email-template source override, returned after a successful write.

object
template
required

The trimmed registered template name saved by this request.

string
Example
admin_test
part
required

The saved source part: subject, text or html.

string
body
required

The saved source text, before rendering with recipient data. This write doesn’t include or change other parts.

string
updated_at

The row’s update timestamp, when available. It isn’t a delivery time or a concurrency token.

string format: date-time

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Request shape is valid but the action doesn’t apply (e.g. subtitles on a non-video/audio asset).

object
error
required

Human-readable error summary

string
Example
the request could not be completed