Email Templates

Create typed reusable email content for workflows and campaigns

Email templates own typed content: subject, preheader, HTML body, variable contracts, and preview data. Sender identity belongs to the mailbox selected when tenant email is sent.

Create Email Template

POST /v1/stores/{storeId}/email-templates

SDK: sdk.cms.emailTemplate.create()

const template = await sdk.cms.emailTemplate.create({
key: 'campaign-feature-update',
type: 'campaign_email',
subject: { en: '{{subject}}' },
preheader: '{{preheader}}',
body: '<h1>{{title}}</h1><div>{{body}}</div>',
variables: [
  { key: 'subject', required: true, source: 'template' },
  { key: 'preheader', required: false, source: 'template' },
  { key: 'title', required: true, source: 'template' },
  { key: 'body', required: true, source: 'template' }
],
sample_data: {
  subject: 'June update',
  preheader: 'A few updates from the team.',
  title: 'June update',
  body: '<p>Here is what changed this month.</p>'
}
});

Parameters

Name	Type	Description
`key` required	`string`	Unique template identifier
`type` required	`EmailTemplateType`	Typed purpose and delivery contract
`subject` required	`Record<string, string>`	Localized subject template
`body` required	`string`	HTML body with Handlebars variables
`preheader` optional	`string`	Inbox preview text template
`variables` optional	`EmailTemplateVariable[]`	Variable contract used by validation and the editor
`sample_data` optional	`Record<string, unknown>`	Preview data and example values

Note

Templates never contain From or Reply-To fields. Tenant sends use the selected mailbox; platform authentication email uses the platform sender.

Template Variables

Template expressions use Handlebars paths such as {{subject}} and {{store.name}}. Each root has an explicit contract:

source: 'template' is operator-provided content.
source: 'system' is supplied from authoritative product data.
required controls validation before send.
Newsletter templates must visibly reference {{contact_list.manage_url}}; hidden footer injection is not used.
Contact-list-backed newsletter delivery separately adds the RFC 8058 one-click header pair from the membership token. Those transport headers are not editable template variables.

See RFC 8058 and the Gmail sender guidelines for the delivery requirements behind this contract.

Preview Email Template

POST /v1/stores/{storeId}/email-templates/{id}/preview

SDK: sdk.cms.emailTemplate.preview()

const preview = await sdk.cms.emailTemplate.preview({
  id: 'tmpl_abc123',
  vars: {
    subject: 'June update',
    title: 'June update',
    body: '<p>Here is what changed this month.</p>'
  }
});

console.log(preview.subject, preview.html, preview.warnings);

List Email Templates

GET /v1/stores/{storeId}/email-templates

SDK: sdk.cms.emailTemplate.find()

const { items, cursor } = await sdk.cms.emailTemplate.find({
  query: 'campaign',
  status: 'active',
  limit: 20
});

Update Email Template

PUT /v1/stores/{storeId}/email-templates/{id}

SDK: sdk.cms.emailTemplate.update()

await sdk.cms.emailTemplate.update({
  id: 'tmpl_abc123',
  subject: { en: '{{subject}}' },
  body: '<h1>{{title}}</h1><div>{{body}}</div>',
  status: 'active'
});

Parameters

Name	Type	Description
`id` required	`string`	Template ID
`key` optional	`string`	New key
`type` optional	`EmailTemplateType`	New typed purpose
`subject` optional	`Record<string, string>`	Updated localized subject templates
`body` optional	`string`	Updated HTML body
`preheader` optional	`string`	Updated preheader
`variables` optional	`EmailTemplateVariable[]`	Updated variable declarations
`sample_data` optional	`Record<string, unknown>`	Updated sample data
`status` optional	`active \| archived`	Template status

Default Templates

Every new store includes typed templates for:

Key	Purpose
`order-notification-store`	Order notification to the store
`order-notification-contact`	Order confirmation to the contact
`order-reminder-contact`	Scheduled order-item reminder
`contact-notification-store`	Contact-form submission notification
`subscription-confirm`	Contact-list double opt-in confirmation
`campaign-simple-email`	General campaign email
`newsletter-basic`	Contact-list-backed campaign email

Note

Campaign messages keep their rendered subject, HTML, and text snapshots. Editing a template later does not rewrite sent history.