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.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The registered template name, for example admin_test. Surrounding whitespace is trimmed; matching is case-sensitive.
The part to replace: subject, text or html. The named template must ship it. Surrounding whitespace is trimmed.
Request Body required
Section titled “Request Body required ”Replacement source for the template and part in the request path.
object
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.
Responses
Section titled “ Responses ”The saved source override and its update timestamp when available.
One saved email-template source override, returned after a successful write.
object
The trimmed registered template name saved by this request.
Example
admin_testThe saved source part: subject, text or html.
The saved source text, before rendering with recipient data. This write doesn’t include or change other parts.
The row’s update timestamp, when available. It isn’t a delivery time or a concurrency token.
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completedResource not found
object
Human-readable error summary
Example
the request could not be completedRequest shape is valid but the action doesn’t apply (e.g. subtitles on a non-video/audio asset).
object
Human-readable error summary
Example
the request could not be completed