/v1/workspaces/{workspace_id}/templatesAuthCreate or update a template, layout, or partial. Idempotent on (workspace_id, name); `kind` cannot change after the first upsert.
Path parameters
workspace_id*string · uuidId of the workspace.
Headers
Idempotency-KeystringOpaque client-generated string (1–256 chars, `[A-Za-z0-9._:-]`) used to deduplicate retries within a 24h window. A retry with the same key and body returns the original response with `Idempotent-Replay: true`.
Request body
name*stringUnique template name within the app (lowercase letters, digits, underscore, hyphen)
Example: "order-confirmation"
kindenum (3)Kind: "template" (sendable email; default), "layout" (chrome wrapper referenced via {{> layout.<name>}}), "partial" (reusable block referenced via {{> partial.<name>}}). Cannot be changed after create — delete + recreate to switch kinds.
subject*stringSubject line (Handlebars). Layouts and partials ignore this field — they are not standalone-sendable. Pass an empty string for those.
body_html*stringHTML body (Handlebars)
body_textstringPlain-text body (Handlebars). Auto-derived if omitted.
variables_schemaobjectDeclared variable schema. Shape: `{version:1, vars:{<name>:{type, required?, default?, options?}}}`. When set, render + send validate the payload against the schema and 400 with descriptive errors on mismatch.
tagsarrayWorkspace-scoped labels for organizing templates. Free-form strings; the editor surfaces existing tags as autocomplete.
Response · 201
id*string · uuidThe template id.
workspace_id*string · uuidThe workspace that owns the template.
name*stringTemplate name, unique in the workspace; used in send URLs.
kind*objectWhat the template is: a sendable `template`, a `layout` that wraps templates, or a `partial` included by them.
subject*stringSubject line (Handlebars).
body_html*stringHTML body (Handlebars).
body_text*stringPlain-text body (Handlebars); null to derive it from the HTML.
variables_schema*objectDeclared variable schema (`{ version: 1, vars: { <name>: { type, required?, default?, description?, options? } } }`), as stored; null if not configured.
tags*arrayTags for organising templates.
created_at*string · date-timeWhen the template was created.
updated_at*string · date-timeWhen the template was last changed.
source*objectWhere this row came from. 'manual' for UI-authored, 'github' for rows maintained by the workspace GitHub integration sync. Migration 0020.
source_ref*stringStable provider pointer used by the editor to build "Open on GitHub →" links. Shape: `github:<owner>/<repo>@<branch>:<path-in-repo>`.
source_synced_at*string · date-timeWhen the sync service last wrote this row. null for manual rows.
Example
Request
POST https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/templates
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"name": "order-confirmation",
"kind": "template",
"subject": "string",
"body_html": "string",
"body_text": "string",
"variables_schema": {},
"tags": [
"string"
]
}Response
{
"id": "00000000-0000-0000-0000-000000000000",
"workspace_id": "00000000-0000-0000-0000-000000000000",
"name": "string",
"kind": {},
"subject": "string",
"body_html": "string",
"body_text": "string",
"variables_schema": {},
"tags": [
"string"
],
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"source": {},
"source_ref": "string",
"source_synced_at": "2026-01-01T00:00:00.000Z"
}