Templates

SDK reference for creating, managing, and previewing email templates in Kraiter.

The kraiter.templates namespace provides methods for managing email templates. Templates define the subject line and MJML body of your emails. They support Liquid variables for dynamic content.

upsert

Creates a template, or replaces it if one already exists with the given ID. The template ID is passed as the first argument; the body is passed as the second.

const template = await kraiter.templates.upsert('tmpl_welcome', {
  name: 'Welcome Email',
  subject: 'Welcome to {{ companyName }}, {{ firstName }}!',
  content: `
    <mjml>
      <mj-body>
        <mj-section>
          <mj-column>
            <mj-text>Hi {{ firstName }}, thanks for signing up!</mj-text>
          </mj-column>
        </mj-section>
      </mj-body>
    </mjml>
  `,
});

Parameters

Parameter	Type	Required	Description
`templateId`	`string`	Yes	A unique identifier for the template (first argument). Use a consistent prefix like `tmpl_`.
`name`	`string`	Yes	A human-readable name for the template.
`subject`	`string`	Yes	The email subject line. Supports Liquid variables.
`content`	`string`	Yes	The template body in MJML markup.

Returns

Promise<Template> — the created or replaced template object.

Errors

Code	When
`VALIDATION_ERROR`	The MJML is invalid or required fields are missing.

get

Retrieves a template by ID. Returns null if not found. Pass includeContent: true to include the MJML body.

const template = await kraiter.templates.get('tmpl_welcome');

if (template) {
  console.log(template.name, template.subject);
}

// Include the MJML body
const full = await kraiter.templates.get('tmpl_welcome', true);

Parameters

Parameter	Type	Required	Description
`templateId`	`string`	Yes	The template ID.
`includeContent`	`boolean`	No	When `true`, the returned object includes the `content` (MJML body).

Returns

Promise<Template | TemplateWithContent | null> — the template object (with content when includeContent is true), or null if not found.

list

Lists templates with cursor-based pagination.

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

for (const template of page.items) {
  console.log(template.templateId, template.name);
}

Parameters

Parameter	Type	Required	Description
`limit`	`number`	No	Maximum items per page.
`cursor`	`string`	No	Pagination cursor from a previous response's `nextCursor`.

Returns

Promise<{ items: Template[]; nextCursor?: string }> — a page of template objects.

update

Updates an existing template. Only the fields you include are changed.

const updated = await kraiter.templates.update('tmpl_welcome', {
  subject: 'Welcome aboard, {{ firstName }}!',
});

Parameters

Parameter	Type	Required	Description
`templateId`	`string`	Yes	The template ID to update.
`name`	`string`	No	Updated template name.
`subject`	`string`	No	Updated subject line.
`content`	`string`	No	Updated MJML body.
`enabled`	`boolean`	No	Whether the template is enabled for sending.
`disableReason`	`string`	No	A note describing why the template was disabled.

Returns

Promise<Template> — the updated template object.

Errors

Code	When
`NOT_FOUND`	No template exists with this ID.
`VALIDATION_ERROR`	The updated MJML is invalid.

delete

Permanently deletes a template.

await kraiter.templates.delete('tmpl_welcome');

Parameters

Parameter	Type	Required	Description
`templateId`	`string`	Yes	The template ID to delete.

Returns

Promise<void>

Errors

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

preview

Renders a template with the given variables and returns the compiled HTML and subject line. Useful for showing a preview in your UI before sending.

const { subject, htmlBody } = await kraiter.templates.preview('tmpl_welcome', {
  firstName: 'Alice',
  companyName: 'Acme',
});

console.log(subject);  // "Welcome to Acme, Alice!"
console.log(htmlBody); // compiled HTML output

Parameters

Parameter	Type	Required	Description
`templateId`	`string`	Yes	The template ID to preview.
`variables`	`Record<string, unknown>`	No	Variables to interpolate into the template.

Returns

Promise<RenderPreviewResult> — an object with the following fields:

Field	Type	Description
`subject`	`string`	The interpolated subject line.
`htmlBody`	`string`	The compiled HTML body.
`textBody`	`string`	The plain-text body, when available.

Errors

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

listVersions

Lists the version history for a template with cursor-based pagination. Each time a template is upserted, a new version is recorded.

const page = await kraiter.templates.listVersions('tmpl_welcome');

for (const version of page.items) {
  console.log(version.version, version.createdAt);
}

Parameters

Parameter	Type	Required	Description
`templateId`	`string`	Yes	The template ID.
`limit`	`number`	No	Maximum items per page.
`cursor`	`string`	No	Pagination cursor.

Returns

Promise<{ items: TemplateVersion[]; nextCursor?: string }> — a page of version records.

Errors

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

getVersion

Retrieves a specific version of a template by its version identifier. Returns null if not found.

const version = await kraiter.templates.getVersion('tmpl_welcome', 'v2');

if (version) {
  console.log(version.version, version.createdAt);
  console.log(version.content); // the template content at this version
}

Parameters

Parameter	Type	Required	Description
`templateId`	`string`	Yes	The template ID.
`version`	`string`	Yes	The version identifier.

Returns

Promise<TemplateVersion | null> — the version record, or null if not found.

Errors

Code	When
`NOT_FOUND`	No template or version exists with these IDs.

Templates

On this page