Save mail template. PUT /api/openapi/v1/mail-templates/{template_id}, scope admin.v1.mail-settings.manage.
- Scope: admin.v1.mail-settings.manage
- Permission: Manage enterprise mail (mail-settings)
- Permission type: Manage
- Endpoint: PUT/api/openapi/v1/mail-templates/{template_id}
Authentication and request headers
Call with an application API key. This endpoint checks only the scope above; read, manage and execute permissions do not imply one another.
| Name | Location | Type | Required | Description | Example |
|---|---|---|---|---|---|
| Authorization | header | string | Yes | Application API key, passed as a Bearer token. | Bearer qwk_*** |
| X-Request-Id | header | string | No | Optional request tracing identifier; generated by the server if omitted. | req-20260831-001 |
Request parameters
| Name | Location | Type | Required | Description | Example |
|---|---|---|---|---|---|
| template_id | path | string | Required | Template ID | "<string>" |
| html | body | string | Required | HTML body | "<string>" |
| subject | body | string | Required | Email subject | "<string>" |
| text | body | string | Required | Plain text body | "<string>" |
| version | body | integer · int64 | Required | Version used for concurrent update checks | 0 |
Request example
cURL
Responses
200 OK
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| customized | boolean | Yes | Whether the template is customized | false |
| default | OpenapifacadeMailContent | Yes | Default template | {"html":"<string>","subject":"<string>","text":"<string>"} |
| default.html | string | Yes | HTML body | "<string>" |
| default.subject | string | Yes | Email subject | "<string>" |
| default.text | string | Yes | Plain text body | "<string>" |
| id | string | Yes | Mail template ID | "<string>" |
| source | OpenapifacadeMailContent | Yes | Current template | {"html":"<string>","subject":"<string>","text":"<string>"} |
| source.html | string | Yes | HTML body | "<string>" |
| source.subject | string | Yes | Email subject | "<string>" |
| source.text | string | Yes | Plain text body | "<string>" |
| updated_at | string · date-time | No | Updated at | "2026-08-27T10:00:00Z" |
| using_legacy_default | boolean | Yes | Whether the legacy default template is in use | false |
| variable_definitions | array ｜ null | Yes | Template variable definitions | [{"code":"<string>","display_name":"<string>","example":"<string>","max":0,"max_length":0,"min":0,"pattern":"<string>","purpose":"<string>","rendered":false,"required":false,"type":"<string>"}] |
| version | integer · int64 | Yes | Version used for concurrent update checks | 0 |
default Flat business error
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| code | string | No | Stable business error code | "<string>" |
| detail | string | Yes | Human-readable error description | "<string>" |
| details | OpenapiErrorDetails | No | Test result details | {"field":"<string>","reason":"<string>","suggestion":"<string>"} |
| details.field | string | No | Request field that failed validation | "<string>" |
| details.reason | string | No | Stable validation failure reason | "<string>" |
| details.suggestion | string | No | Suggested normalized value | "<string>" |
| error | string | Yes | Stable HTTP error type | "<string>" |