Mail Templates
HTML email templates used by the platform for transactional and workflow emails (share invitations, password recovery, factory notifications, etc.). Each template has a name, subject pattern, and body markup; the runtime renders templates with context variables at send time.
Scopes
| Scope | Reach |
|---|---|
mail_templates:read | Listing, reading, viewing filters. |
mail_templates:write | Creating, updating, deleting templates. |
Endpoints
List Mail Templates
GET /api/mailtemplates/
Returns a page of mail templates.
Required scope: mail_templates:read · also accepts API key
Query parameters — standard pagination set; see Conventions › Pagination. Defaults: sort_by=created, sort_order=desc, hydrate=true.
Response 200 — MailTemplateInDbCursorPage
Get Mail Template Filter Metadata
GET /api/mailtemplates/filters
Returns filter/operator/sort options for List Mail Templates.
Required scope: mail_templates:read
Response 200 — open metadata object.
Get Mail Template by ID
GET /api/mailtemplates/{id}
Returns a single mail template.
Required scope: mail_templates:read · also accepts API key
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Template ID. |
Response 200 — MailTemplateRead
Create Mail Template
POST /api/mailtemplates/
Creates a new mail template.
Required scope: mail_templates:write
Request body — MailTemplateWriteCreate
Response 201 — MailTemplateRead
Update Mail Template by ID
PUT /api/mailtemplates/{id}
Replaces a mail template.
Required scope: mail_templates:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Template ID. |
Request body — MailTemplateWriteReplace
Response 200 — MailTemplateRead
Patch Mail Template
PATCH /api/mailtemplates/{id}
Partial mail template update.
Required scope: mail_templates:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Template ID. |
Request body — MailTemplateWriteUpdate
Response 200 — MailTemplateRead
Delete Mail Template by ID
DELETE /api/mailtemplates/{id}
Removes a mail template. Workflow steps and share-email actions that reference a deleted template will fail at send time — verify nothing depends on the template before deleting.
Required scope: mail_templates:write
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Template ID. |
Response 204 — empty.
See also
- Asset Store › Shares › Send Share Email — a common consumer of mail templates.
- Factory › Builder Helpers — a read-only view of these templates used by the workflow editor.
- Themes — visual branding (separate from email templates).