Email Templates

Helmdesk uses Handlebars for email templating. Upload .hbs files as templates, layouts, or partials via the API or dashboard.

Template format

Templates support metadata comments for subject lines and layout assignment. Partial references are validated on upload.

{{!-- subject: Welcome to {{companyName}} --}}
{{!-- layout: default --}}

<h1>Hello {{name}}</h1>
<p>Welcome aboard!</p>
{{> footer}}

Import API

POST/api/v1/email-templates/import

Upload a .hbs file as a template, layout, or partial (multipart form data).

// Using the SDK
await helmdesk.emails.templates.import(
  fileContent,     // string or Blob
  'welcome.hbs',
  { type: 'template' }
)

// Using fetch
const form = new FormData()
form.append('file', file)
form.append('type', 'template')
await fetch('/api/v1/email-templates/import', {
  method: 'POST',
  headers: { Authorization: 'Bearer sk_live_...' },
  body: form,
})

Shared templates

Account-level templates, layouts, and partials are shared across all projects. Reference them using the @account/ prefix.

POST/api/v1/account/email-templates/import

Upload a .hbs file to the account scope (shared across all projects).

// Upload a shared layout
await helmdesk.emails.templates.import(
  layoutHtml,
  'default.hbs',
  { type: 'layout', scope: 'account' }
)

// Send using a shared template
await helmdesk.emails.send({
  templateKey: '@account/welcome',
  to: { email: 'user@example.com' },
})

// Reference shared partials in any template
// {{> @account/footer}}

Resolution order

• Templates: @account/key resolves from account scope explicitly
• Layouts: Project layouts first, then account layouts as fallback
• Partials: Project partials take priority; account partials used as fallback for unmatched keys