Templates

Templates API

Manage email templates with MJML support, Handlebars variables, versioning, and preview.

GET /v1/templates

List all templates for the organization, with pagination.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number
`limit`	integer	`20`	Items per page (max 100)

Response

{
  "data": [
    {
      "id": "tpl-uuid",
      "organizationId": "org-uuid",
      "name": "Welcome Email",
      "description": "Sent on signup",
      "tags": ["onboarding"],
      "currentVersionId": "ver-uuid",
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-01-20T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5,
    "totalPages": 1
  }
}

POST /v1/templates

Create a new template.

Request Body

Field	Type	Required	Description
`name`	`string`	Yes	Template name (max 255 chars).
`description`	`string`	No	Template description (max 2,000 chars).
`tags`	`string[]`	No	Up to 20 tags for categorization.

Response

Status: 201 Created

{
  "data": {
    "id": "tpl-uuid",
    "organizationId": "org-uuid",
    "name": "Welcome Email",
    "description": "Sent on signup",
    "tags": ["onboarding"],
    "currentVersionId": null,
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T10:00:00Z"
  }
}

GET /v1/templates/:id

Get a template with its current version content.

Response

{
  "data": {
    "id": "tpl-uuid",
    "name": "Welcome Email",
    "description": "Sent on signup",
    "tags": ["onboarding"],
    "currentVersionId": "ver-uuid",
    "currentVersion": {
      "id": "ver-uuid",
      "templateId": "tpl-uuid",
      "versionNumber": 3,
      "mjmlSource": "<mjml>...</mjml>",
      "htmlContent": "<html>...</html>",
      "textContent": "Plain text version...",
      "variablesSchema": { "name": "string", "activationUrl": "string" },
      "createdBy": "user-uuid",
      "createdAt": "2025-01-20T14:30:00Z"
    }
  }
}

PATCH /v1/templates/:id

Update template metadata (name, description, tags).

Request Body

Field	Type	Required	Description
`name`	`string`	No	New template name.
`description`	`string`	No	New description.
`tags`	`string[]`	No	New tags.

DELETE /v1/templates/:id

Delete a template and all its versions (cascade).

Status: 200 OK

{ "success": true }

Template Versions

POST /v1/templates/:id/versions

Create a new template version. The version number auto-increments and the new version is automatically set as the current version.

If mjmlSource is provided, it is compiled to HTML. Validation errors are returned if the MJML is invalid.

Request Body

Field	Type	Required	Description
`htmlContent`	`string`	Yes	Compiled HTML content.
`mjmlSource`	`string`	No	MJML source (compiled server-side if provided).
`textContent`	`string`	No	Plain text fallback.
`variablesSchema`	`object`	No	JSON schema describing expected variables.

Response

Status: 201 Created

{
  "data": {
    "id": "ver-uuid",
    "templateId": "tpl-uuid",
    "versionNumber": 4,
    "mjmlSource": "<mjml>...</mjml>",
    "htmlContent": "<html>...</html>",
    "textContent": null,
    "variablesSchema": null,
    "createdBy": "user-uuid",
    "createdAt": "2025-01-22T09:00:00Z"
  }
}

GET /v1/templates/:id/versions

List all versions of a template (version number and metadata, without full content).

{
  "data": [
    {
      "id": "ver-uuid-4",
      "templateId": "tpl-uuid",
      "versionNumber": 4,
      "createdBy": "user-uuid",
      "createdAt": "2025-01-22T09:00:00Z"
    },
    {
      "id": "ver-uuid-3",
      "templateId": "tpl-uuid",
      "versionNumber": 3,
      "createdBy": "user-uuid",
      "createdAt": "2025-01-20T14:30:00Z"
    }
  ],
  "currentVersionId": "ver-uuid-4"
}

GET /v1/templates/:id/versions/:versionId

Get a specific version with full content (HTML, MJML source, text).

POST /v1/templates/:id/preview

Render a template with sample variables and return the HTML output. Useful for previewing templates before sending.

Request Body

Field	Type	Required	Description
`variables`	`object`	No	Sample variable values.
`versionId`	`string`	No	Specific version to preview. Defaults to current version.

Response

{
  "html": "<html><body><h1>Hello Jane!</h1>...</body></html>",
  "text": "Hello Jane! ..."
}

POST /v1/templates/:id/rollback/:versionId

Set a previous version as the current version.

Response

{
  "data": {
    "templateId": "tpl-uuid",
    "currentVersionId": "ver-uuid-2",
    "versionNumber": 2
  }
}