Templates

Create, update, list, and preview email templates built with MJML and Liquid variables.

Templates define the content and layout of your emails. They are written in MJML for responsive rendering and support Liquid variables for personalisation.

Create or update template

PUT /api/templates/:id

Creates a new template or updates an existing one. This endpoint is idempotent — calling it multiple times with the same ID and body produces the same result.

Path parameters

Parameter	Type	Description
`id`	string	A unique identifier for the template (e.g. `welcome-email`, `password-reset`).

Request body

Field	Type	Required	Description
`id`	string	Yes	Must match the path parameter.
`name`	string	Yes	Human-readable name for the template.
`subject`	string	Yes	Email subject line. Supports Liquid variables (e.g. `Welcome, {{ firstName }}!`).
`mjml`	string	Yes	The MJML source for the email body.
`variables`	string[]	No	List of variable names used in the template. Used for validation and the preview UI.

Response

Returns the created or updated template.

{
  "id": "welcome-email",
  "name": "Welcome Email",
  "subject": "Welcome, {{ firstName }}!",
  "mjml": "<mjml><mj-body>...</mj-body></mjml>",
  "variables": ["firstName", "dashboardUrl"],
  "version": 3,
  "createdAt": "2025-09-10T08:00:00.000Z",
  "updatedAt": "2025-09-15T14:00:00.000Z"
}

Errors

Code	Description
`VALIDATION_ERROR`	Missing required fields or invalid MJML syntax.

Examples

curl -X PUT https://api.kraiter.com/api/templates/welcome-email \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "welcome-email",
    "name": "Welcome Email",
    "subject": "Welcome, {{ firstName }}!",
    "mjml": "<mjml><mj-body><mj-section><mj-column><mj-text>Hello {{ firstName }}, welcome to Kraiter!</mj-text></mj-column></mj-section></mj-body></mjml>",
    "variables": ["firstName"]
  }'

const template = await kraiter.templates.put("welcome-email", {
  id: "welcome-email",
  name: "Welcome Email",
  subject: "Welcome, {{ firstName }}!",
  mjml: "<mjml><mj-body><mj-section><mj-column><mj-text>Hello {{ firstName }}, welcome to Kraiter!</mj-text></mj-column></mj-section></mj-body></mjml>",
  variables: ["firstName"],
});

List templates

GET /api/templates

Returns a paginated list of templates.

Query parameters

Parameter	Type	Default	Description
`cursor`	string	—	Pagination cursor from a previous response.
`limit`	number	20	Number of templates to return (max 100).

Response

{
  "data": [
    {
      "id": "welcome-email",
      "name": "Welcome Email",
      "subject": "Welcome, {{ firstName }}!",
      "version": 3,
      "createdAt": "2025-09-10T08:00:00.000Z",
      "updatedAt": "2025-09-15T14:00:00.000Z"
    }
  ],
  "nextCursor": null
}

Examples

curl "https://api.kraiter.com/api/templates?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

const templates = await kraiter.templates.list({ limit: 10 });

Get template

GET /api/templates/:id

Returns a single template including its full MJML source.

Path parameters

Parameter	Type	Description
`id`	string	The template ID.

Errors

Code	Description
`NOT_FOUND`	No template with this ID exists.

Examples

curl https://api.kraiter.com/api/templates/welcome-email \
  -H "Authorization: Bearer YOUR_API_KEY"

const template = await kraiter.templates.get("welcome-email");

Delete template

DELETE /api/templates/:id

Permanently deletes a template. Sequences referencing this template will fail on their next send.

Path parameters

Parameter	Type	Description
`id`	string	The template ID.

Response

Returns 204 No Content on success.

Errors

Code	Description
`NOT_FOUND`	No template with this ID exists.

Examples

curl -X DELETE https://api.kraiter.com/api/templates/welcome-email \
  -H "Authorization: Bearer YOUR_API_KEY"

await kraiter.templates.delete("welcome-email");

List template versions

GET /api/templates/:id/versions

Returns the version history for a template. Each time a template is updated via PUT, a new version is created.

Path parameters

Parameter	Type	Description
`id`	string	The template ID.

Response

{
  "data": [
    {
      "version": 3,
      "subject": "Welcome, {{ firstName }}!",
      "updatedAt": "2025-09-15T14:00:00.000Z"
    },
    {
      "version": 2,
      "subject": "Welcome to Kraiter!",
      "updatedAt": "2025-09-12T09:00:00.000Z"
    }
  ],
  "nextCursor": null
}

Examples

curl "https://api.kraiter.com/api/templates/welcome-email/versions" \
  -H "Authorization: Bearer YOUR_API_KEY"

const versions = await kraiter.templates.listVersions("welcome-email");

Preview template

POST /api/templates/:id/preview

Renders the template with the provided variables and returns the resulting HTML. Use this to preview how an email will look before sending.

Path parameters

Parameter	Type	Description
`id`	string	The template ID.

Request body

Field	Type	Required	Description
`variables`	object	No	Key-value pairs to inject into the template.

Response

{
  "subject": "Welcome, Alice!",
  "html": "<!doctype html><html>..."
}

Examples

curl -X POST https://api.kraiter.com/api/templates/welcome-email/preview \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "variables": { "firstName": "Alice" } }'

const preview = await kraiter.templates.preview("welcome-email", {
  variables: { firstName: "Alice" },
});
console.log(preview.html);

Templates

On this page