Edit on GitHub

Custom Email Templates

Svelte Guardian sends various emails for authentication flows such as email verification, password reset, and two-factor authentication. This guide shows you how to customize these email templates to match your application’s branding and requirements.

Default Email Templates

By default, Svelte Guardian provides simple but functional email templates for:

  • Email verification
  • Password reset
  • Two-factor authentication codes
  • Welcome emails
  • Security notifications

These templates include your application’s name, necessary links or codes, and brief instructions.

Customization Options

There are several ways to customize email templates in Svelte Guardian:

  1. Basic Configuration: Simple text and branding changes
  2. Custom HTML Templates: Complete control over email design
  3. Dynamic Templates: Templates with custom variables and logic
  4. Template Providers: Integration with email services like SendGrid, Mailjet, etc.

Basic Configuration

For simple customization, you can modify text and branding in your Svelte Guardian configuration:

// src/hooks.server.ts const { handle } = await guardianAuth({ // Other config... security: { emailProvider: { // Email provider config... branding: { appName: 'Your App Name', appUrl: 'https://yourdomain.com', logo: 'https://yourdomain.com/logo.png', primaryColor: '#4F46E5', footerText: '© 2025 Your Company. All rights reserved.' } } } });

This will customize the default templates with your branding elements.

Custom HTML Templates

For more control, provide your own HTML templates:

const { handle } = await guardianAuth({ security: { emailProvider: { // Other email config... templates: { verificationEmail: { subject: 'Verify your email for {{appName}}', htmlTemplate: './src/emails/verification.html', textTemplate: './src/emails/verification.txt' }, passwordReset: { subject: 'Reset your password for {{appName}}', htmlTemplate: './src/emails/password-reset.html', textTemplate: './src/emails/password-reset.txt' }, twoFactorCode: { subject: 'Your two-factor authentication code', htmlTemplate: './src/emails/two-factor.html', textTemplate: './src/emails/two-factor.txt' }, welcome: { subject: 'Welcome to {{appName}}!', htmlTemplate: './src/emails/welcome.html', textTemplate: './src/emails/welcome.txt' } } } } });

HTML templates can use variables with the {{variable}} syntax.

Example HTML Template

Here’s an example verification email template (./src/emails/verification.html):

Verify your email address

Hello {{name}},

Thank you for signing up for {{appName}}. To complete your registration, please verify your email address.

{{#if otpMethod}}

Your verification code is:

{{otp}}

Enter this code on the verification page to confirm your email address.

{{else}}

Click the button below to verify your email address:

Verify Email

If the button doesn't work, you can also copy and paste this link into your browser:

{{verificationUrl}}

{{/if}}

This {{#if otpMethod}}code{{else}}link{{/if}} will expire in {{expirationMinutes}} minutes.

If you didn't create an account with us, you can safely ignore this email.

{{footerText}}

{{appName}} - {{appUrl}}

Available Template Variables

VariableDescriptionExample
{{appName}}Your application name“Svelte Guardian”
{{appUrl}}Your application URL”https://example.com”
{{logo}}URL to your logo”https://example.com/logo.png”
{{primaryColor}}Your brand color“#4F46E5”
{{name}}User’s name“John Doe”
{{email}}User’s email”john@example.com”
{{otp}}Verification/reset code“123456”
{{verificationUrl}}Full verification URL”https://example.com/verify?token=abc123”
{{resetUrl}}Full password reset URL”https://example.com/reset?token=abc123”
{{expirationMinutes}}Expiration time in minutes“15”
{{footerText}}Custom footer text”© 2025 Your Company”

Dynamic Templates with Template Functions

For more complex templates with logic, provide template functions instead of static files:

const { handle } = await guardianAuth({ security: { emailProvider: { templates: { verificationEmail: { subject: (data) => `Verify your ${data.appName} account`, html: (data) => { const { user, otp, url, appName, expiryMinutes } = data; // Generate HTML with conditional logic return `

Welcome to ${appName}, ${user.name || 'there'}!

Your verification code is: ${otp}

`; }, text: (data) => { // Plain text version return `Verify your ${data.appName} account Your code: ${data.otp}`; } } } } } });

Using Template Providers

For advanced email needs, you can integrate with template providers like SendGrid, Mailjet, or Mailchimp:

import { sendgridTemplateProvider } from 'svelte-guardian/email'; const { handle } = await guardianAuth({ security: { emailProvider: { type: 'sendgrid', apiKey: process.env.SENDGRID_API_KEY, templateProvider: sendgridTemplateProvider({ templates: { verificationEmail: 'd-abc123456789', passwordReset: 'd-def123456789', twoFactorCode: 'd-ghi123456789', welcome: 'd-jkl123456789' }, defaultSender: { email: 'no-reply@yourdomain.com', name: 'Your App Name' } }) } } });

Testing Email Templates

To test your email templates during development:

  1. Enable console logging for emails:
const { handle } = await guardianAuth({ security: { emailProvider: { // Regular email config... debug: process.env.NODE_ENV !== 'production' // Log emails to console in development } } });
  1. Or use a development email service like Mailhog or Ethereal:
const { handle } = await guardianAuth({ security: { emailProvider: process.env.NODE_ENV === 'production' ? productionEmailProvider : { type: 'nodemailer', host: 'localhost', port: 1025, // Mailhog secure: false, auth: { user: '', pass: '' } } } });

Localization

For multi-language support, use template functions with translations:

import i18n from '$lib/i18n'; // Your translation system const { handle } = await guardianAuth({ security: { emailProvider: { templates: { verificationEmail: { subject: (data) => { const locale = data.user.locale || 'en'; return i18n.t('email.verification.subject', { appName: data.appName }, locale); }, html: (data) => { const locale = data.user.locale || 'en'; return renderTemplate('verification-email', { ...data, t: (key) => i18n.t(key, {}, locale) }); } } } } } });

Best Practices for Email Templates

  1. Always include plain text versions for better deliverability and accessibility
  2. Keep your design responsive for mobile devices
  3. Test across email clients (Gmail, Outlook, Apple Mail, etc.)
  4. Use inline CSS as many email clients strip <style> tags
  5. Keep emails simple and focused on a single call to action
  6. Include your company’s physical address to comply with anti-spam laws
  7. Provide clear unsubscribe options for marketing emails

Next Steps

Share this page
← Advanced Route Protection Email Verification and Password Reset →