Email Templates

Create reusable email templates with variable substitution.

Template Basics

Templates are created in the ArtaMail dashboard. Each template has:

• slug - Unique identifier used in API calls (e.g., "welcome", "password-reset")
• name - Human-readable name
• subject - Email subject line (can include variables)
• html - Email body with styling
• text - Plain text fallback
• variables - Dynamic content placeholders

Variable Syntax

Use double curly braces for variables in your templates. Identity fields ({{brand}}, {{legal_entity}}, {{legal_address}}, {{legal_details}}) are auto-filled from Settings → Brand & compliance — you only pass app-specific values at send time:

<h1>Welcome, {{name}}!</h1>
<p>Thanks for joining {{brand}}.</p>
<a href="{{verifyUrl}}">Verify your email</a>
<footer style="margin-top: 32px; font-size: 12px; color: #666;">
  <p>© {{legal_entity}}. All rights reserved.</p>
  <p>{{legal_address}}</p>
  <p>{{legal_details}}</p>
</footer>

Variables in subject lines work the same way:

Welcome to {{brand}}, {{name}}!

Sending with Variables

Pass app-specific values in the data object. Identity variables are injected automatically — omit them unless overriding:

await sendEmail({
  to: '[email protected]',
  template: 'welcome',
  data: {
    name: 'John Doe',
    verifyUrl: 'https://example.com/verify/abc123',
  },
});

Template Categories

Transactional

Triggered by user actions. These are high-priority and always sent:

• Welcome emails
• Password reset
• Order confirmations
• Account notifications
• Double opt-in confirmation (consent-confirm preset)

Marketing

Promotional content that respects unsubscribe preferences:

• Newsletters
• Product announcements
• Promotional offers

Listing Templates

Get available templates via the API:

const templates = await artamail.listTemplates();
for (const t of templates) {
  console.log(`${t.slug}: ${t.name}`);
  console.log('  Variables:', t.variables.join(', '));
  console.log('  Category:', t.category);
}

Getting Template Details

Check a specific template's requirements:

const template = await artamail.getTemplate('welcome');
if (template) {
  console.log('Subject:', template.subject);
  console.log('Required variables:', template.variables);
  console.log('Version:', template.version);
} else {
  console.log('Template not found');
}

Unsubscribe & consent variables

Marketing templates should include unsubscribe or preference links. ArtaMail substitutes these at send time (signed tokens + your org preferences_url_template when set). Do not pass them in API data — they are reserved system variables. Use a separate account per brand for isolated preference domains — see Multiple Products. Identity variables {{brand}}, {{legal_entity}}, {{legal_address}}, and {{legal_details}} are auto-injected from account Settings. For double opt-in, use consent-confirm with {{confirm_url}} and an optional success redirect on the template.

Template Versioning

Each template has a version number that increments when you update it in the dashboard. Emails always use the current version at send time.

Best Practices

Use Descriptive Slugs

• welcome- New user welcome
• password-reset- Password reset request
• order-confirmation- Purchase confirmation
• invoice-paid- Payment received

Keep Variables Consistent

Use the same variable names across templates where applicable:

• name- Recipient's name
• email- Recipient's email
• brand- Product identity (auto-injected)
• legal_entity- Legal name for footers (auto-injected)
• legal_address- Postal address for footers (auto-injected when set)
• legal_details- Registration IDs, court register, etc. (auto-injected when set)
• company- Legacy alias for brand — avoid in new templates
• supportUrl- Link to support

Provide Fallbacks

Handle missing variables gracefully in your templates:

<p>Hello {{name | default: 'there'}}!</p>

Test Before Sending

Use test API keys and preview in the dashboard before going live:

# Development environment
ARTAMAIL_API_KEY=am_test_sk_xxx
# Emails won't actually be sent, but you'll see them in the dashboard