Skip to main content

Email Templates

This guide covers the email templates used in your application for various authentication and user management flows. All email templates are pre-designed with a modern, responsive layout and include your application's branding.

Template Development​

The email templates are developed using Maizzle, a framework for building responsive HTML emails with Tailwind CSS. The source files and build configuration are located in the packages/maizzle-email-builder package.

Features and Location​

Maizzle provides the following features for email development:

  • Tailwind CSS: Use Tailwind's utility classes for styling
  • Responsive Design: Built-in responsive email layouts
  • CSS Inlining: Automatically inlines CSS for better email client compatibility
  • CSS Optimization: Removes unused CSS and optimizes for production
  • Asset Management: Handles images and other assets, placing them in the public directory of your application

The built templates are located in the apps/web/supabase/templates directory and include:

  • verify-email.html: Template for email verification during signup
  • magic-link.html: Template for magic link authentication
  • reset-password.html: Template for password reset requests
  • email-change.html: Template for email change confirmation

Building and Customizing​

To build the email templates:

  1. Run pnpm maizzle:build in the root directory of your project
  2. The optimized HTML templates will be generated in apps/web/supabase/templates

To customize the templates:

  1. Modify the template source files in packages/maizzle-email-builder/src/templates using Tailwind CSS and Maizzle's features
  2. Modify the packages/maizzle-email-builder/config.js and packages/maizzle-email-builder/config.production.js files according to your requirements to customize the build process
  3. Run pnpm maizzle:build to generate the optimized templates
  4. Test the templates using the Inbucket interface in development
tip

If you are testing your email templates in development, you must use the local links inside the packages/maizzle-email-builder/config.js file (especially for the app_url variable in this file).

If you are testing your email templates in production, you must use the production links inside the packages/maizzle-email-builder/config.production.js file.

Configuration​

Template Setup​

Email templates are configured in the supabase/config.toml file:

[auth.email.template.confirmation]
subject = "Confirm your email address"
content_path = "./supabase/templates/verify-email.html"

[auth.email.template.magic_link]
subject = "Sign in with this Magic Link"
content_path = "./supabase/templates/magic-link.html"

[auth.email.template.recovery]
subject = "Reset your password"
content_path = "./supabase/templates/reset-password.html"

[auth.email.template.email_change]
subject = "Confirm your email change"
content_path = "./supabase/templates/email-change.html"

Email Settings​

The following settings can be configured in supabase/config.toml:

[auth.email]
# Allow/disallow new user signups via email
enable_signup = true
# Require email confirmation before sign-in
enable_confirmations = true
# Control frequency of confirmation/reset emails
max_frequency = "1s"
# If enabled, users need to confirm any email change on both old and new email
double_confirm_changes = false

Template Variables​

When sending emails, Supabase automatically includes user data in the templates:

  • {{ .Email }}: User's email address
  • {{ .Data.name }}: User's name (defaults to email username)
  • {{ .SiteURL }}: Your application's URL
  • {{ .TokenHash }}: Verification token
  • {{ .RedirectTo }}: Redirect URL after verification
  • {{ .NewEmail }}: New email address (only for email change templates)

Testing and Best Practices​

Testing Process​

  1. Run your application in development mode
  2. Trigger the email flow you want to test
  3. Open Inbucket at http://localhost:54324
  4. Check the received email for:
    • Correct template rendering
    • Working links and tokens
    • Proper variable substitution
    • Mobile responsiveness

Best Practices​

  1. Build Process: Always build templates before committing changes
  2. Responsive Design: Use Tailwind's responsive utilities for different screen sizes
  3. Plain Text Alternative: Include plain text versions for better deliverability
  4. Brand Consistency: Maintain consistent branding across all templates
  5. Clear CTAs: Make action buttons prominent and clear
  6. Test Links: Always verify that authentication links work correctly
  7. Email Client Testing: Test templates across different email clients