Emails

Send transactional emails using Handlebars templates with layouts, partials, and per-environment configuration. Each environment (production, staging, development) uses its own provider config and sender identity.

POST/api/v1/emails/send

Send a transactional email using a registered template. Supports idempotency keys to prevent duplicate sends.

const result = await helmdesk.emails.send({
  templateKey: 'welcome',
  to: { email: 'user@example.com', name: 'Jane' },
  variables: { activationUrl: 'https://...' },
  environment: 'production',
}, { idempotencyKey: 'signup-jane-2024' })

POST/api/v1/emails/preview

Preview a rendered email template without sending. Uses sample data if no variables are provided.

const { subject, html } = await helmdesk.emails.preview({
  templateKey: 'welcome',
  variables: { name: 'Test User' },
})

GET/api/v1/email-templates/:key/schema

Get the template variable schema (auto-detected from Handlebars expressions).

const schema = await helmdesk.emails.getTemplateSchema('welcome')
// schema.variables -> [{ name: 'activationUrl', required: true }]

Environments

Each project can configure separate email providers for production, staging, and development. Sending modes include live, sandbox (redirects to a test address), allowlist (only certain domains), and paused.

See Email Templates for the template import API and shared template system.