Mail API reference

Mail API · Templates

post/v1/workspaces/{workspace_id}/templatesAuth

Create or update a template, layout, or partial. Idempotent on (workspace_id, name); `kind` cannot change after the first upsert.

Path parameters

workspace_id*string · uuid

Id of the workspace.

Headers

Idempotency-Keystring

Opaque 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*string

Unique 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*string

Subject line (Handlebars). Layouts and partials ignore this field — they are not standalone-sendable. Pass an empty string for those.

body_html*string

HTML body (Handlebars)

body_textstring

Plain-text body (Handlebars). Auto-derived if omitted.

variables_schemaobject

Declared 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.

tagsarray

Workspace-scoped labels for organizing templates. Free-form strings; the editor surfaces existing tags as autocomplete.

Response · 201

id*string · uuid

The template id.

workspace_id*string · uuid

The workspace that owns the template.

name*string

Template name, unique in the workspace; used in send URLs.

kind*object

What the template is: a sendable `template`, a `layout` that wraps templates, or a `partial` included by them.

subject*string

Subject line (Handlebars).

body_html*string

HTML body (Handlebars).

body_text*string

Plain-text body (Handlebars); null to derive it from the HTML.

variables_schema*object

Declared variable schema (`{ version: 1, vars: { <name>: { type, required?, default?, description?, options? } } }`), as stored; null if not configured.

tags*array

Tags for organising templates.

created_at*string · date-time

When the template was created.

updated_at*string · date-time

When the template was last changed.

source*object

Where this row came from. 'manual' for UI-authored, 'github' for rows maintained by the workspace GitHub integration sync. Migration 0020.

source_ref*string

Stable 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-time

When 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"
}