Templates

Create a template

Create a workspace template with a server-backed draft.

POST/api/v1/templates

On this page

Authentication

Send a RouteKite API key as a Bearer token. This endpoint requires the template:write scope.

Required headers
Name	Type	Requirement	Description
`Authorization`	string	Required	Bearer API key with the required workspace scope.Example: `Bearer rk_your_key`
`Content-Type`	string	Required	Must be application/json.Example: `application/json`

Request body

Request fields
Name	Type	Requirement	Description
`name`	string	Required	Template name from 2 to 120 characters.
`description`	string \| null	Optional	Description up to 500 characters.
`purpose`	marketing \| transactional	Required	Immutable compliance purpose.
`source_mode`	visual \| html	Optional	Immutable authoring mode. Defaults to visual.
`subject`	string	Optional	Initial subject from 1 to 998 characters. Defaults to the name.
`preview_text`	string	Optional	Initial preview text up to 240 characters.
`document`	RouteKite document	Optional	Canonical document matching purpose and source_mode. A blank document is generated when omitted.

Response

Response fields
Name	Type	Requirement	Description
`object`	string	Always	Always template.
`id`	uuid	Always	The template identifier.
`name`	string	Always	The template name.
`description`	string \| null	Always	Optional template description.
`purpose`	marketing \| transactional	Always	The immutable compliance purpose.
`source_mode`	visual \| html	Always	The immutable authoring mode.
`state`	draft \| published	Always	The current template state.
`industry`	string \| null	Always	Optional industry metadata.
`tone`	string \| null	Always	Optional tone metadata.
`published_version_id`	uuid \| null	Always	The current immutable published version.
`created_at`	date-time	Always	When the template was created.
`updated_at`	date-time	Always	When the template metadata or state last changed.
`draft.revision`	integer	When saved	The server-authoritative draft revision.
`draft.base_published_version_id`	uuid \| null	When saved	The published version the draft was based on.
`draft.schema_version`	integer	When saved	The canonical document schema version.
`draft.source_document`	object	When saved	The canonical editable document.
`draft.requires_save`	boolean	When saved	True only when RouteKite presented the exact prior canonical compliance footer with current locked markers. Save this returned document before Publish.
`draft.subject`	string	When saved	The saved subject.
`draft.preview_text`	string	When saved	The saved inbox preview text.

Immutable identity

purpose and source_mode are fixed at creation. Omit document to start with RouteKite's canonical blank document for that purpose and mode.

Errors

Status	Code	What it means	What to do
400	`INVALID_REQUEST / INVALID_JSON / INVALID_CURSOR`	The JSON, identifier, field, document, or cursor is invalid.	Correct the reported input.
400	`INVALID_TEMPLATE_DOCUMENT`	The document is invalid or its purpose and source mode do not match the template.	Submit a canonical RouteKite document matching the template.
401	`UNAUTHORIZED`	The API key is missing, invalid, revoked, or expired.	Check the Bearer header and active key.
403	`FORBIDDEN`	The key lacks the required template scope.	Use template:read or template:write as documented for the operation.
429	`RATE_LIMITED`	Too many template requests were sent.	Honor Retry-After before retrying.
500	`TEMPLATE_OPERATION_FAILED / INTERNAL_ERROR`	The template operation could not complete.	Retry after a short delay.
403	`API_KEY_ACTOR_UNAVAILABLE`	The key creator is no longer a workspace member.	Replace the API key with one created by a current member.
413	`PAYLOAD_TOO_LARGE`	The request body exceeds 1,100,000 bytes.	Reduce the document or request metadata.
422	`COMPLIANCE_REQUIRED / TEMPLATE_COMPILATION_FAILED / SOURCE_UNAVAILABLE`	A marketing compliance block is missing or hidden, the draft cannot compile, or a source has no saved content to duplicate.	Restore the canonical visible compliance block, or correct and save the source content.

Related documentation

Save a template draftReplace the canonical server draft using optimistic concurrency.Publish a templateCompile and publish one exact saved draft revision.

Request

1const response = await fetch("https://routekite.com/api/v1/templates", {2  method: "POST",3  headers: {4    "Authorization": `Bearer ${process.env.ROUTEKITE_API_KEY}`,5    "Content-Type": "application/json",6  },7  body: JSON.stringify({8  "name": "Order receipt",9  "description": "Sent after checkout.",10  "purpose": "transactional",11  "source_mode": "visual",12  "subject": "Your receipt",13  "preview_text": "Order details inside."14}),15});16 17const data = response.status === 204 ? null : await response.json();

201 Created

1{2  "object": "template",3  "id": "27fdc190-3a56-46f0-89e8-88ac64a5087d",4  "name": "Order receipt",5  "description": "Sent after checkout.",6  "purpose": "transactional",7  "source_mode": "visual",8  "state": "draft",9  "industry": null,10  "tone": null,11  "published_version_id": null,12  "created_at": "2026-09-02T10:30:00.000Z",13  "updated_at": "2026-09-02T10:30:00.000Z",14  "draft": {15    "revision": 1,16    "base_published_version_id": null,17    "schema_version": 1,18    "source_document": {"schemaVersion":1,"engine":"routekite-grapesjs-mjml","purpose":"transactional","sourceMode":"visual","brand":{},"body":{"mjml":"<mjml><mj-body><mj-section><mj-column><mj-text>Your receipt is ready.</mj-text></mj-column></mj-section></mj-body></mjml>"},"variables":[],"conditions":[],"sampleData":{}},19    "requires_save": false,20    "subject": "Your receipt",21    "preview_text": "Order details inside.",22    "created_at": "2026-09-02T10:30:00.000Z",23    "updated_at": "2026-09-02T10:30:00.000Z"24  }25}