To customize email templates in Supabase, go to Authentication > Email Templates in the Dashboard and edit the HTML for confirmation, magic link, password reset, and invite emails. Use template variables like {{ .ConfirmationURL }}, {{ .Token }}, and {{ .SiteURL }} to insert dynamic values. Configure a custom SMTP provider first to remove the default 2 emails per hour rate limit before sending branded emails in production.
Customizing Auth Email Templates in Supabase
Supabase sends transactional emails for signup confirmation, magic links, password resets, and user invites. The default templates are plain text and generic. This tutorial shows you how to replace them with branded HTML emails using Supabase's template variables, and how to configure a custom SMTP provider for reliable delivery.
Prerequisites
- A Supabase project with Authentication enabled
- Access to the Supabase Dashboard
- Basic HTML knowledge for writing email templates
- A custom SMTP provider (Resend, SendGrid, or Mailgun) for production use
Step-by-step guide
Navigate to the email templates editor
Navigate to the email templates editor
In the Supabase Dashboard, go to Authentication in the left sidebar, then click Email Templates. You will see tabs for each email type: Confirm signup, Magic link, Change email address, and Reset password. Each tab has an HTML editor where you can modify the email subject line and body. The Invite user template is also here if you use the invite flow. Select the template you want to customize.
Expected result: The email template editor is open showing the current HTML template and subject line for the selected email type.
Understand the available template variables
Understand the available template variables
Supabase uses Go template syntax with double curly braces for dynamic variables. The key variables available across all templates are: {{ .ConfirmationURL }} — the full URL the user clicks to confirm their action; {{ .Token }} — the raw OTP token (6-digit code); {{ .TokenHash }} — the hashed token for PKCE flows; {{ .SiteURL }} — your project's site URL from the URL Configuration settings; {{ .RedirectTo }} — the redirect URL passed in the auth call. Not all variables are available in every template type — ConfirmationURL and Token are the most commonly used.
Expected result: You understand which template variables are available and what values they contain.
Create a branded confirmation email template
Create a branded confirmation email template
Replace the default plain text template with a branded HTML email. Use inline CSS styles since most email clients strip external stylesheets. Include your company logo, brand colors, and a clear call-to-action button using the {{ .ConfirmationURL }} variable. Keep the design simple and mobile-friendly — most email clients have limited CSS support.
1<html>2<body style="font-family: Arial, sans-serif; background-color: #f4f4f4; padding: 20px;">3 <div style="max-width: 600px; margin: 0 auto; background: #ffffff; border-radius: 8px; padding: 40px;">4 <h1 style="color: #1a1a1a; font-size: 24px; margin-bottom: 16px;">Confirm your email</h1>5 <p style="color: #666666; font-size: 16px; line-height: 1.5;">6 Thanks for signing up! Click the button below to confirm your email address and activate your account.7 </p>8 <a href="{{ .ConfirmationURL }}" style="display: inline-block; background-color: #3ECF8E; color: #ffffff; text-decoration: none; padding: 12px 24px; border-radius: 6px; font-weight: bold; margin: 24px 0;">Confirm Email</a>9 <p style="color: #999999; font-size: 14px;">If you didn't sign up, you can safely ignore this email.</p>10 </div>11</body>12</html>Expected result: The confirmation email template is updated with branded HTML, a styled button linking to {{ .ConfirmationURL }}, and consistent branding.
Customize the subject line for each template
Customize the subject line for each template
Above each HTML editor, there is a Subject field where you can customize the email subject line. Use a clear, action-oriented subject that matches the email purpose. The subject line also supports the same template variables, though most apps use static text. Keep subjects under 50 characters for mobile display and avoid spam trigger words like 'free', 'urgent', or excessive punctuation.
Expected result: Each email type has a customized subject line that is clear, branded, and mobile-friendly.
Configure custom SMTP for reliable delivery
Configure custom SMTP for reliable delivery
Supabase's built-in email service has a 2 emails per hour rate limit. For production, configure a custom SMTP provider. Go to Project Settings > Authentication in the Dashboard, scroll to the SMTP Settings section, and toggle Enable Custom SMTP. Enter your SMTP host, port, username, password, and sender email address. Popular providers include Resend (recommended for simplicity), SendGrid, Postmark, and Mailgun. After saving, all auth emails will be sent through your SMTP provider with no rate limit.
Expected result: Custom SMTP is configured and all auth emails are sent through your provider, bypassing the 2 per hour rate limit.
Test your email templates
Test your email templates
Create a test user account to trigger each email type and verify your templates render correctly. Sign up with a new email to test the confirmation template. Use the password reset flow to test the reset template. If you have magic links enabled, request one to test that template. Check that all links work, the branding looks correct, and the email lands in the inbox (not spam). If emails go to spam, verify your SMTP provider's domain authentication (SPF, DKIM, DMARC records).
1// Trigger a confirmation email by signing up2const { data, error } = await supabase.auth.signUp({3 email: 'test@yourdomain.com',4 password: 'test-password-123',5})67// Trigger a password reset email8const { error: resetError } = await supabase.auth.resetPasswordForEmail(9 'test@yourdomain.com',10 { redirectTo: 'https://yourapp.com/reset-password' }11)Expected result: All email templates are tested, links work correctly, and emails arrive in the inbox with the correct branding.
Complete working example
1<!-- Supabase Email Template: Confirm Signup -->2<html>3<body style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background-color: #f4f4f5; padding: 20px; margin: 0;">4 <div style="max-width: 600px; margin: 0 auto; background: #ffffff; border-radius: 8px; overflow: hidden;">5 <!-- Header -->6 <div style="background-color: #3ECF8E; padding: 24px; text-align: center;">7 <h1 style="color: #ffffff; margin: 0; font-size: 20px;">Your App Name</h1>8 </div>9 <!-- Body -->10 <div style="padding: 32px 24px;">11 <h2 style="color: #1a1a1a; font-size: 22px; margin: 0 0 16px;">Confirm your email address</h2>12 <p style="color: #4a4a4a; font-size: 16px; line-height: 1.6; margin: 0 0 24px;">13 Welcome! Please confirm your email address by clicking the button below.14 This link will expire in 24 hours.15 </p>16 <a href="{{ .ConfirmationURL }}"17 style="display: inline-block; background-color: #3ECF8E; color: #ffffff;18 text-decoration: none; padding: 14px 28px; border-radius: 6px;19 font-weight: 600; font-size: 16px;">20 Confirm Email Address21 </a>22 <p style="color: #999999; font-size: 14px; margin-top: 32px; line-height: 1.5;">23 If you didn't create an account, no action is needed.24 This link will expire automatically.25 </p>26 </div>27 <!-- Footer -->28 <div style="background-color: #f9fafb; padding: 16px 24px; text-align: center;">29 <p style="color: #9ca3af; font-size: 12px; margin: 0;">30 © 2026 Your App Name. All rights reserved.31 </p>32 </div>33 </div>34</body>35</html>Common mistakes when customizing Email Templates in Supabase
Why it's a problem: Using external CSS stylesheets or style tags in the head that get stripped by email clients
How to avoid: Always use inline CSS styles on each HTML element. Most email clients (especially Gmail and Outlook) strip external stylesheets and style blocks from the head.
Why it's a problem: Not configuring custom SMTP and wondering why only 2 emails per hour are sent
How to avoid: Supabase's built-in email service has a strict 2 emails per hour limit. Configure a custom SMTP provider like Resend or SendGrid in Project Settings > Authentication > SMTP Settings.
Why it's a problem: Using {{ .ConfirmationURL }} in templates where it is not available
How to avoid: The ConfirmationURL variable is available in confirmation, magic link, and invite templates. For password reset, use the same variable but verify it generates the correct reset link.
Why it's a problem: Forgetting to set the Site URL in Authentication > URL Configuration
How to avoid: The {{ .SiteURL }} variable and redirect behavior depend on the Site URL setting. Go to Authentication > URL Configuration and set your production URL. Add any additional redirect URLs to the Redirect URLs allowlist.
Best practices
- Always configure a custom SMTP provider before going to production
- Use inline CSS for all email styling to ensure cross-client compatibility
- Include a fallback text link below styled buttons for email clients that block HTML
- Set up SPF, DKIM, and DMARC records for your sending domain to prevent emails landing in spam
- Keep email templates simple and mobile-responsive with a max-width of 600px
- Test templates in multiple email clients (Gmail, Outlook, Apple Mail) before deploying
- Include a clear explanation of why the user received the email for trust and compliance
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
I need to customize the Supabase auth email templates for my SaaS app. Create branded HTML email templates for signup confirmation, password reset, and magic link with my brand color #3B82F6. Use the correct Supabase template variables and inline CSS for email client compatibility.
Create a complete set of branded email templates for Supabase Auth: signup confirmation, password reset, magic link, and invite. Use {{ .ConfirmationURL }} for action buttons, inline CSS for styling, and include a header with the app logo, a body with the action button, and a footer with the company name.
Frequently asked questions
What template variables are available in Supabase email templates?
The main variables are {{ .ConfirmationURL }} (the action link), {{ .Token }} (the raw OTP code), {{ .TokenHash }} (hashed token for PKCE), {{ .SiteURL }} (your site URL), and {{ .RedirectTo }} (the redirect URL from the auth call). Not all variables are available in every template type.
Can I use images in Supabase email templates?
Yes, use img tags with absolute URLs pointing to publicly hosted images. Do not use base64-encoded images as they increase email size and are blocked by some clients. Host images on your CDN or Supabase Storage public bucket.
Why are my custom emails going to spam?
This is usually a domain authentication issue. Set up SPF, DKIM, and DMARC records for your sending domain. Also verify that your sender email address matches the domain. Most SMTP providers like Resend and SendGrid have setup guides for these records.
Can I send emails in multiple languages?
Supabase does not have built-in multi-language template support. You can use a single template with the primary language or implement language switching through an Edge Function that sends emails via your SMTP provider's API instead of using Supabase's built-in templates.
What is the default rate limit for Supabase auth emails?
The built-in Supabase email service is limited to 2 emails per hour per recipient. This is intended for development only. Configure a custom SMTP provider to remove this limit for production.
Can I preview email templates before sending them?
Supabase does not have a built-in preview feature. Copy your HTML into an email testing tool like Litmus, Email on Acid, or a local HTML file. Then trigger the email by signing up with a test account to see the actual rendered result.
Can RapidDev help design and implement branded email templates for my Supabase project?
Yes, RapidDev can create custom email templates that match your brand identity, configure your SMTP provider, and ensure reliable email delivery with proper domain authentication.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation