Email Templates API

The Email Templates API lets administrators customize the transactional emails sent by Auris. Each of the thirteen template types corresponds to a specific event (verification, password reset, magic link, security alerts, …) and can be customized with HTML and dynamic variables, independently per locale.

Auris ships with default templates for all types in five locales (en, it, fr, de, es). When a custom template exists for a type and locale, it is used for all future emails of that type; otherwise the branded default is used. Resolution order at send time: custom (requested locale) -> custom (en) -> default (requested locale) -> default (en).

All endpoints require a Bearer token with the manage:security permission and select the tenant via the x-tenant header (the tenant’s realm identifier).

List Templates

Success response (200)

{
  "templates": [
    {
      "type": "verification",
      "label": "Email Verification",
      "description": "Sent when a new user registers to verify their email address.",
      "variables": ["email", "link", "expiresIn", "year", "month", "day", "date"],
      "hasCustomTemplate": true,
      "active": true,
      "updatedAt": "2026-07-20T10:00:00.000Z",
      "customLocales": ["en", "it"]
    }
  ],
  "availableLocales": ["en", "it", "fr", "de", "es"],
  "wellKnownLocales": { "en": "English", "it": "Italiano", "pt-BR": "Português (Brasil)" }
}

Get Template

Success response (200)

{
  "type": "verification",
  "locale": "it",
  "label": "Email Verification",
  "description": "Sent when a new user registers to verify their email address.",
  "variables": ["email", "link", "expiresIn", "year", "month", "day", "date"],
  "hasCustomTemplate": false,
  "subject": null,
  "htmlBody": null,
  "metadata": null,
  "active": true,
  "updatedAt": null,
  "defaultSubject": "Verifica il tuo indirizzo email",
  "defaultHtmlBody": "<!DOCTYPE html>...",
  "availableLocales": ["en", "it", "fr", "de", "es"],
  "customLocales": ["en"],
  "hasDefaultTemplate": true,
  "wellKnownLocales": { "en": "English", "it": "Italiano" }
}

subject, htmlBody, and metadata are null when no custom template exists for the requested locale. defaultSubject and defaultHtmlBody always contain the built-in template, rendered with the tenant’s branding (logo, color, white-label footer) exactly as a live send would use it. hasDefaultTemplate indicates whether the requested locale has a built-in default (en, it, fr, de, es); other locales fall back to English.

Error responses

Update Template

Request body

{
  "subject": "Verify your email — {{email}}",
  "htmlBody": "<!DOCTYPE html><html><body><h1>Verify your email</h1><p>Hello {{email}},</p><p><a href=\"{{link}}\">Confirm your address</a></p><p>The link expires in {{expiresIn}}.</p></body></html>",
  "locale": "en",
  "metadata": { "source": "code" }
}

The HTML body is sanitized on the server before storage: <script> tags, event handler attributes (onclick, …), javascript:/data: URIs, <iframe>/<embed>/<object>/<form>/<base> tags, and dangerous CSS constructs are stripped.

Success response (200) — the saved template record:

{
  "id": "cltpl123",
  "tenantId": "tnt_ScUtrVKUKGxtu7WY",
  "type": "verification",
  "locale": "en",
  "subject": "Verify your email — {{email}}",
  "htmlBody": "<!DOCTYPE html>...",
  "metadata": { "source": "code" },
  "active": true,
  "createdAt": "2026-07-23T09:00:00.000Z",
  "updatedAt": "2026-07-23T09:00:00.000Z"
}

Error responses

Delete Template

Success response (200)

{ "success": true }

Preview Template

Request body

{
  "subject": "Verify your email — {{email}}",
  "htmlBody": "<!DOCTYPE html>..."
}

Success response (200)

{
  "subject": "Verify your email — [email protected]",
  "html": "<!DOCTYPE html>...",
  "variables": {
    "email": "[email protected]",
    "link": "https://console.auris.dev/verify-email?token=abc123",
    "expiresIn": "24 hours",
    "year": "2026",
    "month": "07",
    "day": "23",
    "date": "2026-07-23"
  }
}

The variables field echoes the sample values that were substituted. The HTML body is sanitized before rendering; the subject is rendered as plain text (no HTML escaping of values).

Test Email

Request body

{
  "subject": "Verify your email — {{email}}",
  "htmlBody": "<!DOCTYPE html>...",
  "recipientEmail": "[email protected]"
}

Success response (200)

{ "success": true, "sentTo": "[email protected]" }

Error responses

Template Types

Auris supports thirteen transactional email template types:

The global date variables year, month, day, and date (format YYYY-MM-DD) are auto-injected into every render, in addition to the per-type variables above.

Template Syntax

• {{variable}} — replaced with the value. In the HTML body, values are HTML-escaped automatically to prevent injection; in the subject line values are inserted as plain text.
• {{{variable}}} — raw interpolation without escaping. Only for trusted, server-built HTML fragments.
• {{#if variable}}...{{/if}} — the block is kept only when the variable resolves to a non-empty string; otherwise it is removed entirely (markup included). Example: the magic_link default template renders the secondary approve button only when approveLink is provided.

Unknown placeholders are left as-is in the output. Dot notation and loops are not supported.

<h1>Sign in to {{tenantName}}</h1>
<p><a href="{{link}}">Sign in on this device</a></p>
{{#if approveLink}}
<p><a href="{{approveLink}}">Approve on the original device</a></p>
{{/if}}
<p>The link expires in {{expiresIn}}.</p>

Permissions Reference

Related

• Customizing Email Templates — Step-by-step template customization guide
• Email Templates — Edit templates visually from the Console