apps/www/_blog/2025-12-03-introducing-seven-new-email-templates-for-auth.mdx
Today we're releasing 7 new email notification templates for Supabase Auth. These security-related emails can be used to notify users when sensitive actions happen on their account to help surface any suspicious activity.
For example, a user may receive an email that their password was changed, or that their email address was updated to [email protected].
To start, we're introducing the following security notification email templates:
Each notification includes relevant context depending on the event. For example, the old email when an address changes, the provider name when an identity is linked or unlinked, or the specific MFA method that was modified. This helps users quickly identify whether the action was legitimate.
As part of this release, we've also taken some time to give the Emails section in the Dashboard a refresh and a dedicated section in the sidebar. Each security notification can be enabled or disabled individually, and the content can be customized to match your brand and tone.
You can edit and preview the email templates directly from the Dashboard and use template variables to customize the content.
You can also manage the new security notification templates through the Supabase CLI by updating your supabase/config.toml file:
[auth.email.notification.password_changed]
enabled = true
subject = "Your password has been changed"
content_path = "./templates/password_changed_notification.html"
[auth.email.notification.mfa_factor_enrolled]
enabled = true
subject = "A new MFA method has been added to your account"
content_path = "./templates/mfa_factor_enrolled_notification.html"
where content_path is a relative path to the HTML file for the email template. The notification types can be any of the following:
password_changedemail_changedphone_changedidentity_linkedidentity_unlinkedmfa_factor_enrolledmfa_factor_unenrolledFor more details, see the Local Dev / CLI Configuration Reference.
For programmatic management of the new security notification templates, you can use the Supabase Management API to fetch and update the email templates. For example, to enable the MFA factor enrolled notification and customize its content, you can make a PATCH request to the Auth service configuration endpoint:
# Get your access token from <https://supabase.com/dashboard/account/tokens>
export SUPABASE_ACCESS_TOKEN="your-access-token"
export PROJECT_REF="your-project-ref"
# Update email templates
curl -X PATCH "<https://api.supabase.com/v1/projects/$PROJECT_REF/config/auth>" \
-H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"mailer_notifications_mfa_factor_enrolled_enabled": true,
"mailer_subjects_mfa_factor_enrolled_notification": "A new MFA factor has been enrolled",
"mailer_templates_mfa_factor_enrolled_notification_content": "<h2>A new MFA factor has been enrolled</h2><p>A new factor ({{ .FactorType }}) has been enrolled for your account {{ .Email }}.</p>"
}'
Once enabled, users will receive an email notifying them when their MFA factors have modified on their account.
You can find the complete list of available fields in the Management API reference.
Security notifications are also supported through the Auth email send hook, with new email_action_type values for each notification:
password_changed_notificationemail_changed_notificationphone_changed_notificationidentity_linked_notification / identity_unlinked_notificationmfa_factor_enrolled_notification / mfa_factor_unenrolled_notificationThe hook payload includes contextual data like old_email, provider, and factor_type, enabling custom email providers and internationalization for security notifications.
For example, you can configure the Auth email send hook to send a password changed notification using Resend's brand new email templates feature via a Supabase Edge Function:
import { Webhook } from '<https://esm.sh/[email protected]>'
import { Resend } from 'npm:[email protected]'
const resend = new Resend(Deno.env.get('RESEND_API_KEY'))
const hookSecret = Deno.env.get('SEND_EMAIL_HOOK_SECRET')
Deno.serve(async (req) => {
if (req.method !== 'POST') {
return new Response('method not allowed', {
status: 405,
})
}
const payload = await req.text()
const headers = Object.fromEntries(req.headers)
const wh = new Webhook(hookSecret)
try {
const {
user,
email_data: { email_action_type },
} = wh.verify(payload, headers)
// Handle the different notification types
if (email_action_type === 'password_changed_notification') {
const { error } = await resend.emails.send({
to: user.email,
template: {
id: 'password_changed_notification',
variables: {
CURRENT_EMAIL: user.email,
},
},
})
if (error) {
console.error('failed to send email:', error)
return Response.json(
{
error: {
http_code: error.code,
message: error.message,
},
},
{
status: 500,
}
)
}
}
} catch (error) {
console.error('failed to verify webhook:', error)
return Response.json(
{
error: {
http_code: error.code,
message: error.message,
},
},
{
status: 401,
}
)
}
return Response.json({})
})
Check out the guide for a complete example on how to send Custom Auth Emails with Resend.
We're planning on adding more security-related email notifications in the future, such as notifying a user when a new device has been used to log into their account or when suspicious activity is detected.
We'd love to hear your feedback on which notifications would be most useful for your application and how we can improve the existing templates.
Here are some resources to help you get started:
Have questions or feedback? Join our Discord community or open a GitHub issue.