Customizing Email Templates

Auris sends transactional emails at critical points in the user lifecycle: email verification, password resets, magic link login, team invitations, welcome messages, and MFA notifications. By default, these emails use a clean, functional template with Auris branding. Customizing them lets you replace that branding with your own, ensuring every touchpoint — from the first verification email to a password reset six months later — feels like it comes from your product, not a third-party service.

This guide walks you through editing templates in the Console, using dynamic variables, previewing and testing changes, configuring SMTP for reliable delivery, and managing templates programmatically via the API.

Why Customize Email Templates

Brand consistency. Your users receive emails from your authentication system during their most important interactions: signing up, resetting a password, accepting a team invitation. Generic templates with third-party branding undermine trust and create a disjointed experience. Custom templates ensure every email matches your product’s visual identity — logo, colors, tone of voice.

Regulatory requirements. Depending on your industry and region, transactional emails may need to include specific footer text, data protection notices, unsubscribe information, or company registration details. Custom templates give you full control over what appears in every email.

Improved deliverability. Emails that look professional and include proper sender identification are less likely to be flagged as spam. A well-designed template with your domain, logo, and clear call-to-action signals legitimacy to email providers.

Template Types

Auris includes six email template types. Each serves a specific purpose and is triggered automatically at the appropriate moment.

Template Type	Description	When It Is Sent
`verification`	Email address verification	After user signup or when a user adds a new email address
`password_reset`	Password reset link	When a user requests a password reset via the forgot-password flow
`magic_link`	Passwordless login link	When a user authenticates via magic link (passwordless login)
`invitation`	Team or organization invitation	When an admin invites a user to join a tenant or organization
`welcome`	Welcome message	After a user successfully verifies their email address
`mfa_notification`	MFA status change alert	When MFA is enabled, disabled, or a new method is added to a user’s account

Each template can be customized independently. You might want a colorful, branded verification email but a minimal, text-focused MFA notification.

Step 1: Access the Template Editor

Open the Auris Console and navigate to Settings then Email Templates
You will see a list of all six template types with their current status (default or customized)
Click on the template type you want to edit

The editor opens with the current HTML source on the left and a live preview on the right. If you have not customized a template yet, the editor shows the default Auris template as a starting point.

Step 2: Edit the HTML

The template editor supports full HTML with inline CSS. Most email clients have limited CSS support, so inline styles are the most reliable approach. Avoid external stylesheets, <link> tags, and complex CSS selectors — they are stripped or ignored by many email clients.

Template variables use Mustache-style {{variableName}} syntax. When Auris sends the email, each variable is replaced with the actual value for that user and action.

Here is a complete example template suitable for verification emails:


<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Verify your email</title>
</head>
<body style="margin: 0; padding: 0; background-color: #f4f4f5; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;">
  <table width="100%" cellpadding="0" cellspacing="0" style="padding: 40px 20px;">
    <tr>
      <td align="center">
        <table width="560" cellpadding="0" cellspacing="0" style="background-color: #ffffff; border-radius: 8px; overflow: hidden;">
          <!-- Header with logo -->
          <tr>
            <td style="padding: 32px 40px 24px; text-align: center;">
              <img src="https://yourcompany.com/logo.png" alt="YourCompany" width="140" style="display: block; margin: 0 auto;" />
            </td>
          </tr>
          <!-- Body -->
          <tr>
            <td style="padding: 0 40px 32px;">
              <h1 style="font-size: 22px; font-weight: 600; color: #18181b; margin: 0 0 16px;">
                Verify your email address
              </h1>
              <p style="font-size: 15px; line-height: 1.6; color: #3f3f46; margin: 0 0 24px;">
                Hi {{userName}}, thanks for signing up at {{companyName}}.
                Please verify your email address by clicking the button below.
                This link expires in {{expiresIn}}.
              </p>
              <!-- Action button -->
              <table cellpadding="0" cellspacing="0" style="margin: 0 auto;">
                <tr>
                  <td style="background-color: #2563eb; border-radius: 6px;">
                    <a href="{{actionUrl}}" style="display: inline-block; padding: 12px 32px; color: #ffffff; font-size: 15px; font-weight: 600; text-decoration: none;">
                      Verify Email
                    </a>
                  </td>
                </tr>
              </table>
              <!-- Plain-text fallback URL -->
              <p style="font-size: 13px; line-height: 1.6; color: #71717a; margin: 24px 0 0; word-break: break-all;">
                If the button does not work, copy and paste this URL into your browser:<br />
                {{actionUrl}}
              </p>
            </td>
          </tr>
          <!-- Footer -->
          <tr>
            <td style="padding: 24px 40px; background-color: #fafafa; border-top: 1px solid #e4e4e7;">
              <p style="font-size: 12px; color: #a1a1aa; margin: 0; text-align: center;">
                &copy; 2026 {{companyName}}. All rights reserved.<br />
                123 Main Street, Your City, Country<br />
                <a href="https://yourcompany.com/support" style="color: #a1a1aa;">Contact Support</a>
              </p>
            </td>
          </tr>
        </table>
      </td>
    </tr>
  </table>
</body>
</html>

Use table-based layouts for email templates. While div-based layouts work in modern web browsers, many email clients (especially Outlook on Windows) render tables far more consistently. The example above uses nested tables for reliable cross-client rendering.

Step 3: Use Template Variables

Every template has access to a set of common variables plus type-specific variables. When the email is rendered, Auris replaces each {{variableName}} placeholder with the actual value.

Common Variables (Available in All Templates)

Variable	Description	Example Value
`{{userName}}`	The user’s display name (first name, or full name if available)	`Jane`
`{{userEmail}}`	The user’s email address	`[email protected]`
`{{tenantName}}`	The tenant identifier	`acme-corp`
`{{companyName}}`	The company name configured in branding settings	`Acme Corporation`

Type-Specific Variables

verification, password_reset, magic_link:

Variable	Description	Example Value
`{{actionUrl}}`	The full URL the user must click (verification link, reset link, or magic link)	`https://auth.acme.com/verify?token=abc123`
`{{expiresIn}}`	Human-readable expiration time for the link	`24 hours`

invitation:

Variable	Description	Example Value
`{{inviterName}}`	Name of the person who sent the invitation	`John Smith`
`{{inviterEmail}}`	Email of the person who sent the invitation	`[email protected]`
`{{organizationName}}`	Name of the organization the user is invited to join	`Acme Engineering`
`{{actionUrl}}`	The invitation acceptance URL	`https://auth.acme.com/accept?token=xyz789`
`{{expiresIn}}`	Human-readable expiration time for the invitation	`7 days`

welcome:

Variable	Description	Example Value
`{{loginUrl}}`	The URL where the user can log in to the application	`https://app.acme.com/login`

mfa_notification:

Variable	Description	Example Value
`{{mfaMethod}}`	The MFA method that was changed	`TOTP authenticator app`
`{{actionType}}`	What happened to the MFA method	`enabled`

Variable names are case-sensitive. {{username}} will not be replaced — you must use the exact spelling {{userName}}. If a variable appears as raw {{text}} in a sent email, check for typos in the variable name.

Step 4: Preview

After editing your template, click the Preview button in the editor toolbar. Auris renders the template with realistic sample data so you can see exactly how the final email will look.

The preview replaces variables with dummy values:

{{userName}} becomes Jane Doe
{{userEmail}} becomes [email protected]
{{companyName}} becomes your configured company name (or Your Company if not set)
{{actionUrl}} becomes https://auth.example.com/action?token=sample-token-abc123
{{expiresIn}} becomes 24 hours
{{inviterName}} becomes John Smith

The preview renders in an iframe that simulates email client rendering. Use the width toggle (desktop/mobile) to check how the template looks at different screen sizes.

The preview is a close approximation, but email clients vary significantly in their HTML/CSS support. Always send a test email (Step 5) and check it in your actual email client before going to production.

Step 5: Send a Test Email

To verify how the template actually renders in a real email client:

Click the Send Test button in the editor toolbar
Enter the recipient email address (typically your own)
Click Send

Auris renders the template with sample data and sends it through your configured SMTP server. 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 both desktop and mobile
The footer text is present and accurate
Links are not broken
The email does not land in the spam folder

The test email uses your live SMTP configuration. If SMTP is not configured yet, the test will fail. See the SMTP Configuration section below.

Step 6: Save

Click Save to publish your template changes. Updates take effect immediately for all future emails of that type — there is no separate publish step and no deployment or server restart needed.

If you want to revert to the default Auris template at any time, click the Reset to Default button in the editor. This discards your custom template and restores the original.

Configuring SMTP

Auris does not include a built-in email relay. You must configure an SMTP server so that Auris can send transactional emails on your behalf. Without SMTP, all email-dependent features — magic links, email verification, password resets, invitations — will fail silently.

Setting Up SMTP in Console

Open the Auris Console and navigate to Settings then SMTP
Fill in your SMTP server details
Click Test Connection to verify the configuration
Click Save

SMTP Configuration Fields

Field	Description	Example
Host	SMTP server hostname	`smtp.sendgrid.net`
Port	SMTP port (typically 587 for STARTTLS, 465 for TLS, 25 for unencrypted)	`587`
Username	SMTP authentication username	`apikey`
Password	SMTP authentication password or API key	`SG.xxxxxxxxxxxx`
From Email	The sender email address shown to recipients	`[email protected]`
From Name	The sender display name shown to recipients	`Acme Corporation`
Encryption	Connection security method	`STARTTLS`

Encryption Options

Option	Port	Description
TLS	465	Direct TLS connection (also called SSL or implicit TLS)
STARTTLS	587	Upgrade plain connection to TLS after connecting (recommended)
None	25	No encryption (not recommended, most providers reject this)

Recommended Providers

Any standard SMTP service works with Auris. Here are popular options:

Provider	Free Tier	Notes
SendGrid	100 emails/day	Widely used, good deliverability, API key as SMTP password
Postmark	100 emails/month	Focused on transactional email, excellent deliverability
Amazon SES	62,000 emails/month (from EC2)	Very cost-effective at scale, requires domain verification
Mailgun	100 emails/day (trial)	Developer-friendly, good analytics
Resend	100 emails/day	Modern API, good developer experience

If SMTP is not configured, email features fail silently. Users will not receive verification emails, password reset links, magic links, or invitations. Always configure SMTP before enabling any email-dependent authentication method.

Testing the Connection

After saving your SMTP settings, click the Test Connection button. Auris attempts to connect to the SMTP server, authenticate, and send a test email to the configured “From Email” address. The result is displayed immediately:

Success — Connection established, authentication passed, test email sent
Connection refused — Host or port is wrong, or a firewall is blocking the connection
Authentication failed — Username or password is incorrect
TLS handshake failed — Wrong encryption method for the selected port

DNS Records for Deliverability

To maximize deliverability and avoid spam filters, configure these DNS records for your sending domain:

Record Type	Purpose
SPF (TXT)	Authorizes your SMTP provider to send email on behalf of your domain
DKIM (TXT)	Adds a cryptographic signature to outgoing emails, proving they have not been tampered with
DMARC (TXT)	Tells receiving servers what to do with emails that fail SPF or DKIM checks

Your SMTP provider will give you the exact DNS records to add. For example, SendGrid provides a CNAME record for DKIM and a TXT record for SPF.

Programmatic Template Management

All template operations available in the Console can also be performed via the API. This is useful for CI/CD pipelines, multi-tenant setups where you need to configure templates across many tenants, or infrastructure-as-code workflows.

List All Templates


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

Response:


{
  "ok": true,
  "data": [
    {
      "id": "et_abc123",
      "type": "verification",
      "subject": "Verify your email address",
      "htmlBody": "<!DOCTYPE html>...",
      "isCustomized": true,
      "updatedAt": "2026-01-15T10:00:00Z"
    },
    {
      "id": "et_def456",
      "type": "password_reset",
      "subject": "Reset your password",
      "htmlBody": "<!DOCTYPE html>...",
      "isCustomized": false,
      "updatedAt": null
    }
  ]
}

Update a Template


curl -X PUT https://auth.yourdomain.com/api/email-templates/verification \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Verify your email — {{companyName}}",
    "htmlBody": "<!DOCTYPE html><html>...your custom HTML...</html>"
  }'

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-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "userName": "Jane Doe",
      "userEmail": "[email protected]",
      "actionUrl": "https://auth.example.com/verify?token=test",
      "expiresIn": "24 hours"
    }
  }'

Response:


{
  "ok": true,
  "data": {
    "subject": "Verify your email — Acme Corporation",
    "htmlBody": "<!DOCTYPE html><html>...rendered HTML with variables replaced...</html>"
  }
}

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-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientEmail": "[email protected]"
  }'

Using the Auris SDK

If you are managing templates programmatically from a Node.js backend, you can use the management client from @auris/js:


import { AurisClient } from '@auris/js'
 
const auris = new AurisClient({
  domain: 'auth.yourcompany.com',
  clientId: 'your-m2m-client-id',
  clientSecret: process.env.AURIS_CLIENT_SECRET!,
})
 
// Get an M2M access token
const management = auris.management
 
// Update the verification email template
await management.request('PUT', '/api/email-templates/verification', {
  subject: 'Please verify your email — {{companyName}}',
  htmlBody: `
    <!DOCTYPE html>
    <html>
      <body>
        <h1>Welcome, {{userName}}!</h1>
        <p>Click <a href="{{actionUrl}}">here</a> to verify your email.</p>
        <p>This link expires in {{expiresIn}}.</p>
      </body>
    </html>
  `,
})

Best Practices

Keep templates simple. Email client HTML support is notoriously inconsistent. Outlook on Windows uses the Word rendering engine, Gmail strips <style> blocks, and Apple Mail handles most modern CSS. 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 clickable text. Some email clients do not render HTML buttons correctly, and some users prefer to inspect URLs before clicking. The example template in Step 2 demonstrates this pattern.

Test on multiple email clients. At a minimum, verify your template in Gmail (web), Outlook (desktop), and Apple Mail (mobile). Services like Litmus and Email on Acid can preview your template across dozens of clients automatically.

Include your company name and support contact in the footer. This satisfies anti-spam regulations (CAN-SPAM, GDPR) and gives users a way to reach you if something goes wrong. Use the {{companyName}} variable so the footer stays accurate across tenants.

Do not include sensitive data in email bodies. Never put passwords, full API keys, or personal data beyond what is necessary in emails. Emails are not encrypted in transit between mail servers and may be stored indefinitely in user mailboxes.

Use {{expiresIn}} to set user expectations. Always tell the user how long their action link is valid. A user who receives a verification email but does not click it for 48 hours should know the link has expired, rather than encountering a generic error page.

Version control your templates. If you manage templates via the API, store the HTML source in your repository alongside your application code. This gives you change history, code review, and the ability to roll back to a previous version.

Troubleshooting

Problem	Likely Cause	Solution
Emails not sending at all	SMTP is not configured	Go to Settings then SMTP and configure your mail server. Click Test Connection to verify.
Variables showing as raw `{{text}}`	Typo in variable name	Check the exact variable spelling in the table above. Variable names are case-sensitive — `{{username}}` is not valid, use `{{userName}}`.
Emails going to spam	Missing SPF/DKIM/DMARC records	Configure DNS records for your sending domain as recommended by your SMTP provider.
Preview works but test email fails	SMTP credentials are wrong	Click Test Connection in SMTP settings. Check host, port, username, and password. Verify the encryption method matches the port.
Images not loading in email	Image URLs use HTTP or are blocked	Use HTTPS URLs for all images. Host images on a CDN or reliable server. Some email clients block images by default — include alt text on all `<img>` tags.
Layout broken in Outlook	Using `div`-based layout or external CSS	Switch to table-based layouts with inline styles. Outlook on Windows uses the Word rendering engine, which has very limited CSS support.
Email shows “via sendgrid.net” or similar	Missing custom DKIM/SPF	Configure DKIM with your SMTP provider so that emails appear to come directly from your domain.
Template changes not taking effect	Browser cache showing old preview	Hard-refresh the Console page. Template changes are saved immediately on the server — if the API returns success, the update is live.

Custom Domains — White-label the authentication domain used in email links
Session Management — Configure session lifetimes and token rotation
Security — Attack protection, MFA, and IP rules
Webhooks — Receive real-time notifications when authentication events occur