Customizing Email Templates

Auris sends transactional emails at critical points in the user lifecycle: email verification, password resets, magic link logins, invitations, security alerts, and more. By default these emails use a clean template rendered with your tenant branding (company name, logo, primary color). Customizing them gives you full control over the HTML, so every touchpoint — from the first verification email to a suspicious-login alert months later — matches your product.

This guide walks you through editing templates in the Console, using dynamic variables and conditional blocks, previewing and testing changes, managing languages, and managing templates programmatically via the API.

Template Types

Auris includes thirteen email template types. Each is triggered automatically at the appropriate moment.

Each template can be customized independently, and independently per language.

Step 1: Open the Template Editor

1. Open the Auris Console and navigate to Settings then Email Templates
2. You will see all thirteen template types with their current status (default or customized)
3. Click the template type you want to edit

Step 2: Pick an Editing Mode

The editor offers three modes:

• Theme editor — customize identity (logo, brand name, footer text), colors, typography, buttons, layout, and the body content through visual panels.
• Visual builder — compose the email from blocks on a canvas.
• Code editor — edit raw HTML and CSS. A snippet library provides ready-made starting points.

Whatever mode you use, the result is a full HTML document stored per template type and language. Most email clients have limited CSS support, so inline styles and table-based layouts are the most reliable approach.

Step 3: Use Template Variables

Variables use the {{variableName}} syntax. When Auris sends the email, each placeholder is replaced with the actual value for that user and event. In the body, values are HTML-escaped automatically; in the subject they are inserted as plain text.

Global Variables (Available in All Templates)

Type-Specific Variables

Conditionals and Raw Interpolation

• {{#if variable}}...{{/if}} keeps the enclosed content only when the variable has a non-empty value. The block — markup included — is removed otherwise.
• {{{variable}}} inserts the raw value without HTML escaping. Only use it for trusted, server-built HTML fragments.

Example for a magic_link template:

<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 device where you started signing in</a></p>
{{/if}}
<p>This link expires in {{expiresIn}}.</p>

Step 4: Manage Languages

Built-in default templates exist in five languages: English (en), Italian (it), French (fr), German (de), and Spanish (es). Custom templates can be saved for any locale code (for example pt-BR) via the language picker in the editor.

At send time, Auris resolves the template in this order:

1. Custom template in the recipient’s locale
2. Custom template in English
3. Built-in default in the recipient’s locale
4. Built-in default in English

This means you can customize only the languages you care about — the rest keep working with defaults.

Step 5: Preview

The live preview renders the template with realistic sample data as you edit (for example [email protected] for {{email}} and 24 hours for {{expiresIn}}). Use the device toggle to check desktop, tablet, and mobile widths, or open the fullscreen preview.

Step 6: Send a Test Email

Click Send Test in the editor. Auris renders the template with sample data and sends it to your own email address (the authenticated admin), with the subject prefixed by [TEST]. Via the API you can optionally specify a different recipient with the recipientEmail field.

Check the email in your inbox and verify:

• The logo and images load correctly
• The action button is clickable and properly styled
• The layout looks correct on desktop and mobile
• All placeholders were replaced (no literal {{text}} left)
• The email does not land in the spam folder

Step 7: Save

Click Save to publish. Updates take effect immediately for all future emails of that type and language — no deployment or restart needed. Saved HTML is sanitized on the server (scripts, event handlers, embedded frames are stripped) and must stay under 500 KB.

To revert to the default template for the current language, click Reset to default. This deletes the custom version and restores the built-in, tenant-branded template.

Email Delivery

Auris sends email through your tenant’s SMTP configuration when one is present and active; otherwise the platform default sender is used. You can configure SMTP (host, port, credentials, sender address), run a connection test, and control the email footer at Settings then Email:

• White-label emails removes the “Powered by Altovar” attribution from the default templates’ footer.
• Hide footer omits the footer band entirely.

For deliverability, configure SPF, DKIM, and DMARC DNS records for your sending domain — your email provider supplies the exact values.

Programmatic Template Management

All template operations available in the Console can also be performed via the Email Templates API. All endpoints require the manage:security permission and the x-tenant header.

List All Templates

curl https://auth.yourdomain.com/api/email-templates \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: your-realm"

Returns each type with label, description, variables, hasCustomTemplate, customLocales, plus availableLocales (the five built-in locales).

Get a Template (with Default Baseline)

curl "https://auth.yourdomain.com/api/email-templates/verification?locale=it" \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: your-realm"

Returns the custom subject/htmlBody for that locale (or null), along with defaultSubject/defaultHtmlBody rendered with your tenant branding.

Update a Template

curl -X PUT https://auth.yourdomain.com/api/email-templates/verification \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: your-realm" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Verify your email",
    "htmlBody": "<!DOCTYPE html><html><body><p>Hello {{email}},</p><p><a href=\"{{link}}\">Verify your address</a> — expires in {{expiresIn}}.</p></body></html>",
    "locale": "en"
  }'

Preview a Template

curl -X POST https://auth.yourdomain.com/api/email-templates/verification/preview \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: your-realm" \
  -H "Content-Type: application/json" \
  -d '{ "subject": "Verify your email", "htmlBody": "<p>Hello {{email}}</p>" }'

Returns { "subject": ..., "html": ..., "variables": { ... } } rendered with sample values. Nothing is sent.

Send a Test Email

curl -X POST https://auth.yourdomain.com/api/email-templates/verification/test \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: your-realm" \
  -H "Content-Type: application/json" \
  -d '{ "subject": "Verify your email", "htmlBody": "<p>Hello {{email}}</p>", "recipientEmail": "[email protected]" }'

recipientEmail is optional — without it, the test goes to your own (the authenticated admin’s) inbox. The response is { "success": true, "sentTo": "..." }.

Delete (Reset to Default)

curl -X DELETE "https://auth.yourdomain.com/api/email-templates/verification?locale=it" \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: your-realm"

With ?locale=, only that language’s custom version is deleted. Without it, all locales for the type are deleted.

Best Practices

Keep templates simple. Email client HTML support is notoriously inconsistent. Stick to inline styles, table layouts, and system fonts for the widest compatibility.

Always include a plain-text action URL. Below every action button, include the raw URL as text. Some clients do not render HTML buttons correctly, and some users prefer to inspect URLs before clicking. Auris also derives a text/plain part from your HTML automatically, preserving link targets.

Use {{expiresIn}} to set expectations. Always tell the user how long an action link or code is valid.

Keep the conditional approve button in magic_link. Wrap the secondary button in {{#if approveLink}}...{{/if}} — the variable is empty for flows that do not use cross-device approval, and the conditional removes the button cleanly.

Do not include sensitive data. Never put passwords or full API keys in emails. Emails may be stored indefinitely in user mailboxes.

Version control your templates. If you manage templates via the API, store the HTML source in your repository. This gives you change history, review, and rollback.

Troubleshooting

Related Guides

• Email Templates (Console) — Editor reference and template catalog
• Email Templates API — Full endpoint reference
• Branding — Tenant branding applied to default emails
• Magic Link Login — The flow behind the magic_link template