Skip to main content

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​

ParameterTypeDefaultDescription
pageinteger1Page number
limitinteger20Items 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​

FieldTypeRequiredDescription
namestringYesTemplate name (max 255 chars).
descriptionstringNoTemplate description (max 2,000 chars).
tagsstring[]NoUp 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​

FieldTypeRequiredDescription
namestringNoNew template name.
descriptionstringNoNew description.
tagsstring[]NoNew 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​

FieldTypeRequiredDescription
htmlContentstringYesCompiled HTML content.
mjmlSourcestringNoMJML source (compiled server-side if provided).
textContentstringNoPlain text fallback.
variablesSchemaobjectNoJSON 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​

FieldTypeRequiredDescription
variablesobjectNoSample variable values.
versionIdstringNoSpecific 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
  }
}