Supabase Custom Email Templates: Brand Auth Emails (2026)

Supabase’s email templating system lets you customize the emails your application sends for authentication, like password resets and email confirmations, giving you full control over branding and user experience.

Here’s a Supabase project configured to send custom-branded authentication emails. Imagine a user requesting a password reset:

{
  "type": "password_reset",
  "to": "user@example.com",
  "subject": "Your Password Reset Request",

  "html": "<p>Hello {{ .User.Email }},</p><p>Click here to reset your password: <a href=\"{{ .BaseUrl }}/auth/v1/verify?type=password_reset&token={{ .Token }}\">Reset Password</a></p><p>Thanks,<br>Your App Team</p>"

}

This JSON payload, sent via Supabase’s auth.api.send_email function, dictates the content of the email. The {{ .User.Email }} and {{ .Token }} are dynamic placeholders that Supabase automatically populates. The {{ .BaseUrl }} is also dynamically inserted, usually reflecting your Supabase project’s URL.

The core problem Supabase’s templating solves is the generic, unbranded emails that default authentication flows often produce. When a user interacts with your app during a sensitive moment like resetting a password, a consistent, on-brand experience builds trust and reinforces your application’s identity. Without custom templates, these emails can feel impersonal and even raise security concerns if they don’t match your app’s look and feel.

Internally, Supabase uses a templating engine (similar to Go’s text/template or html/template) to process these payloads. When an authentication event triggers an email (e.g., user.signup, password.reset), Supabase looks for a corresponding template. If a custom template is defined, it uses that; otherwise, it falls back to a default. You define these custom templates within your Supabase project’s dashboard under the "Auth" -> "Email Templates" section.

Here’s how you’d configure a password reset template in the Supabase UI:

Navigate to your Supabase Project Dashboard.
Go to Authentication > Email Templates.
Select the Password Reset tab.
In the Subject field, enter: Your {{ .SiteUrl }} Password Reset Request

In the HTML Body field, you can input your custom HTML. For example:

<!DOCTYPE html>
<html>
<head>
    <title>Password Reset</title>
    <style>
        body { font-family: sans-serif; line-height: 1.6; }
        .container { padding: 20px; max-width: 600px; margin: auto; border: 1px solid #ddd; border-radius: 8px; }
        .button { display: inline-block; padding: 10px 20px; background-color: #007bff; color: white; text-decoration: none; border-radius: 5px; }
    </style>
</head>
<body>
    <div class="container">
        <h1>Password Reset Request</h1>

        <p>Hello <strong>{{ .User.Email }}</strong>,</p>


        <p>We received a request to reset your password for your account on {{ .SiteUrl }}.</p>

        <p>Please click the button below to set a new password:</p>

        <p><a href="{{ .BaseUrl }}/auth/v1/verify?type=password_reset&token={{ .Token }}" class="button">Reset Password</a></p>

        <p>If you did not request a password reset, please ignore this email.</p>

        <p>Thank you,<br>The {{ .SiteUrl }} Team</p>

    </div>
</body>
</html>

Click Save.

The key levers you control are the Subject and the HTML Body. You can use a rich set of variables provided by Supabase, including:

{{ .User.Email }}: The user’s email address.
{{ .Token }}: The unique token for the specific action (e.g., password reset, email verification).
{{ .BaseUrl }}: The base URL for your Supabase project’s API.
{{ .SiteUrl }}: Typically derived from your project’s general settings, representing your application’s public URL.
{{ .PasswordResetUrl }}: A direct URL for password reset (though constructing it with {{ .BaseUrl }} and {{ .Token }} gives more control).

The most surprising thing about Supabase’s email templating is how granularly you can control which email gets which template. While you can set a default for each email type (like "Password Reset"), Supabase also allows you to dynamically select templates based on context if you’re sending emails programmatically via the auth.api.send_email function. This means you could have different password reset templates for different user segments or features within your application, all managed from a single Supabase project.

Beyond the standard templates, you can also send custom emails for any event using supabase.auth.api.send_email('custom_email_type', { to: 'user@example.com', subject: '...', html: '...' }). The custom_email_type is simply a string identifier that you can then use in your frontend or backend logic to decide what to do with the email. The crucial takeaway is that the entire templating system, including dynamic variables and HTML structure, is available for these custom emails as well.

The next hurdle you’ll likely encounter is handling email delivery failures and optimizing for deliverability, which involves configuring your SMTP provider correctly.

More Deep Dives in Supabase