Email Templates and Customization

Helmdesk uses email templates to control the content and appearance of every outgoing email — ticket confirmations, reply notifications, password resets, and transactional messages sent via the API. Templates use Handlebars syntax for dynamic content.

Template Types

Helmdesk has three types of email components:

Templates

Full email templates for specific use cases. Each template defines the subject line and body content. Examples include ticket confirmation, new reply notification, and password reset.

Layouts

Wrapper templates that define the overall email structure — header, footer, branding. A layout wraps around a template to create the final email. This lets you maintain consistent branding across all emails without duplicating HTML.

Partials

Reusable snippets that can be included in templates or layouts. Use partials for elements that appear in multiple templates, like a signature block or social media links.

How Templates Work Together

When Helmdesk sends an email, it assembles the final message in three steps:

Render the template — Handlebars variables are replaced with actual data (ticket subject, customer name, etc.)

Wrap in the layout — The rendered template is inserted into the layout's {{{body}}} placeholder

Include partials — Any {{> partialName}} references are replaced with the partial's content

Handlebars Variables

Templates use double curly braces for variables. The available variables depend on the template type.

Ticket Templates

{{ticketSubject}} — The ticket's subject line

{{ticketBody}} — The ticket's body content (HTML)

{{customerName}} — The customer's display name

{{customerEmail}} — The customer's email address

{{ticketStatus}} — Current status (open, pending, closed)

{{ticketPriority}} — Priority level (low, normal, high, urgent)

{{ticketUrl}} — Direct link to view the ticket

{{projectName}} — The project name

{{replyBody}} — The content of a reply (for reply notifications)

Transactional Templates

{{to}} — Recipient email address

{{subject}} — Email subject line

Any custom variables you pass via the API

Common Variables

{{currentYear}} — The current year (useful for copyright notices)

{{unsubscribeUrl}} — Unsubscribe link (when applicable)

Using Triple Braces

Use triple braces {{{variable}}} when the variable contains HTML that should be rendered, not escaped. For example, {{{ticketBody}}} renders the ticket body as HTML, while {{ticketBody}} would show the raw HTML tags.

Customizing Templates

From the Dashboard

Navigate to your project

Go to Email > Templates in the sidebar

Click on a template to edit it

Modify the subject line and body

Use the Preview tab to see how the email will look

Click Save

Template Editor Features

Live preview — See your changes rendered in real time

Variable autocomplete — Available variables are suggested as you type

HTML support — Write templates in HTML with inline CSS

Test send — Send a test email to yourself before saving

Shared Templates

Account-level templates apply across all projects in your account. Use shared templates when you want consistent email formatting across multiple projects.

To manage shared templates:

Go to Account Settings > Shared Templates from the main dashboard

Create or edit layouts, templates, and partials

These templates are available to all projects in your account

Project-level templates override shared templates with the same name. This lets you set a default at the account level and customize per project when needed.

Sending Emails via the API

Use the Helmdesk API to send transactional emails with your templates:

import Helmdesk from '@helmdesk/sdk'

const client = new Helmdesk({
  apiKey: 'hd_your_api_key',
  projectId: 'your-project-id'
})

// Send using a template
const result = await client.emails.send({
  to: 'customer@example.com',
  templateId: 'welcome-email',
  variables: {
    customerName: 'Jane Doe',
    accountUrl: 'https://app.example.com/login'
  }
})

// Send with inline content (no template)
const result = await client.emails.send({
  to: 'customer@example.com',
  subject: 'Your order has shipped',
  html: '<p>Your order #1234 is on its way.</p>'
})

The API requires an API key with the emails:send scope.

Email Provider Configuration

Helmdesk sends emails through your configured SMTP provider. To set up email sending:

Go to Email > Email Config in the sidebar

Enter your SMTP details:

- Host — Your SMTP server (e.g., smtp.brevo.com)

- Port — Usually 587 (TLS) or 465 (SSL)

- Username — Your SMTP username

- Password — Your SMTP password or API key

- From address — The sender email address

- From name — The sender display name

Click Test Connection to verify your settings

Click Save

Helmdesk supports any SMTP provider: Brevo, SendGrid, Postmark, Amazon SES, Mailgun, or your own mail server.

Best Practices

Keep templates simple. Complex HTML emails break across email clients. Use tables for layout and inline CSS for styling.

Test across clients. Preview your emails in Gmail, Outlook, and Apple Mail before going live. Each renders HTML differently.

Use layouts for branding. Put your logo, colors, and footer in a layout template. Individual templates stay focused on content.

Set up partials for repeated elements. A footer partial with your company address, social links, and unsubscribe link keeps things consistent and easy to update.

Always include plain text. Some email clients prefer plain text. Helmdesk auto-generates a plain text version, but you can customize it.

Use the preview feature. Always preview templates with real data before deploying to production.

Template Import and Export

You can import and export templates via the API:

// Get template schema (for migration)
const schema = await client.emails.getTemplateSchema()

// Import templates from another system
await client.emails.importTemplates({
  templates: [
    {
      name: 'welcome',
      subject: 'Welcome to {{projectName}}',
      body: '<h1>Welcome, {{customerName}}</h1>...',
      type: 'template'
    }
  ]
})

This is useful for migrating from another helpdesk platform or synchronizing templates across environments.