Skip to content
Self-Hosting

自定义邮箱模板

Configure custom email templates with self-hosted Supabase instance.

当运行自托管的 Supabase 实例时，你可以完全自定义 Supabase Auth 发送的邮件。

🌐 When running a self-hosted Supabase instance, you can fully customize emails sent by Supabase Auth.

概览 #

🌐 Overview

Supabase Auth 不会从挂载的 Docker 卷中读取邮件模板。相反，它希望每个模板都能通过返回有效 HTML 模板的 URL 访问。

🌐 Supabase Auth does not read email templates from mounted Docker volumes. Instead, it expects each template to be available at a URL that returns a valid HTML template.

这个网址：

🌐 This URL:

  • 不需要公开
  • 必须能从 auth 服务访问
  • 必须返回一个有效的 Golang HTML 模板

要给 Supabase Auth 提供模板，你需要一个提供静态 HTML 文件的服务。这可以是你选择的任何服务器。唯一的要求是 auth 服务必须能够通过 HTTP GET 请求访问它。

🌐 To provide templates to Supabase Auth, you need a service that serves static HTML files. This can be any server of your choice. The only requirement is that the auth service must be able to reach it via a HTTP GET request.

本指南使用 Caddy 来提供模板。

🌐 This guide uses Caddy for serving templates.

认证邮件模板 #

🌐 Authentication email templates

身份验证邮件模板可以使用以下环境变量进行配置：

🌐 Authentication email templates can be configured using the following environment variables:

  • GOTRUE_MAILER_TEMPLATES_<AUTH_FLOW>：提供自定义模板 URL。如果未设置，则使用默认模板。
  • GOTRUE_MAILER_SUBJECTS_<AUTH_FLOW>：自定义邮件主题。如果未设置，则使用默认主题。
认证流程发送时机
CONFIRMATION当用户注册时，需要验证他们的邮箱
RECOVERY当用户请求重置密码时
MAGIC_LINK当用户请求免密码登录的魔法链接时
INVITE当用户通过邮件邀请加入你的应用时
EMAIL_CHANGE当用户请求更改邮箱地址时
REAUTHENTICATION当用户需要对敏感操作重新认证时

例如：

🌐 For example:

1
GOTRUE_MAILER_TEMPLATES_MAGIC_LINK='<template_url>'
2
GOTRUE_MAILER_SUBJECTS_MAGIC_LINK='<custom_subject>'

示例 #

🌐 Example

下面是一个设置自定义邀请模板的示例配置。

🌐 Below is an example configuration for setting up a custom invite template.

第1步：创建一个 templates 目录 #

🌐 Step 1: Create a templates directory

在现有的 volumes 目录下创建一个 templates 目录，并将你的邮件模板添加到里面。

🌐 Create a templates directory inside the existing volumes directory and add your email templates to it.

你的目录结构应该是这样的：

🌐 Your directory structure should look like this:

1
volumes/
2
  templates/
3
    invite.html

步骤 2：更新 docker-compose.yml#

🌐 Step 2: Update docker-compose.yml

将 auth 服务更新为依赖 templates-server，并传递电子邮件模板的环境变量。然后添加一个 templates-server 服务，从 ./volumes/templates 提供模板。

🌐 Update the auth service to depend on templates-server, and pass the email template environment variables. Then add a templates-server service to serve the templates from ./volumes/templates.

docker-compose.yml
1
services:
2
  auth:
3
    depends_on:
4
      db:
5
        condition: service_healthy
6
      templates-server: # 👈 new dependency
7
        condition: service_started
8
    environment:
9
      GOTRUE_MAILER_TEMPLATES_INVITE: 'http://templates-server/invite.html'
10
      GOTRUE_MAILER_SUBJECTS_INVITE: 'You have been invited'
11
12
  templates-server:
13
    image: caddy:2-alpine
14
    command: ['caddy', 'file-server', '-r', '/templates', '--listen', ':80']
15
    volumes:
16
      - ./volumes/templates:/templates

这个配置的作用 #

🌐 What this configuration does

  • 增加一个 templates-server 服务，它会和 Supabase 服务一起在同一个 Docker 网络中运行。
  • 从 ./volumes/templates 目录提供你的自定义电子邮件模板文件。
  • 保持模板服务器在 Docker 网络内私有（没有公开端口），所以外部无法访问。
  • 允许 auth 服务通过 http://templates-server/<template>.html 获取模板。

步骤3：重启容器 #

🌐 Step 3: Restart containers

1
sh run.sh recreate auth templates-server

通知邮件模板 #

🌐 Notification email templates

通知邮件模板可以使用以下环境变量进行配置：

🌐 Notification email templates can be configured using the following environment variables:

  • GOTRUE_MAILER_NOTIFICATIONS_<NOTIFICATION_TYPE>_ENABLED：启用通知邮件
  • GOTRUE_MAILER_TEMPLATES_<NOTIFICATION_TYPE>_NOTIFICATION：提供自定义模板 URL。如果未设置，则使用默认模板。
  • GOTRUE_MAILER_SUBJECTS_<NOTIFICATION_TYPE>_NOTIFICATION：自定义邮件主题。如果未设置，则使用默认主题。
通知类型发送时机
PASSWORD_CHANGED用户密码更改时
EMAIL_CHANGED用户邮箱地址更改时
PHONE_CHANGED用户电话号码更改时
MFA_FACTOR_ENROLLED用户账户新增多因素认证时
MFA_FACTOR_UNENROLLED用户账户移除多因素认证时
IDENTITY_LINKED用户账户新增关联身份时
IDENTITY_UNLINKED用户账户解绑身份时

例如：

🌐 For example:

1
GOTRUE_MAILER_NOTIFICATIONS_EMAIL_CHANGED_ENABLED='true'
2
GOTRUE_MAILER_TEMPLATES_EMAIL_CHANGED_NOTIFICATION='<template_url>'
3
GOTRUE_MAILER_SUBJECTS_EMAIL_CHANGED_NOTIFICATION='<custom_subject>'

示例 #

🌐 Example

下面是一个设置自定义密码更改通知模板的示例配置。

🌐 Below is an example configuration for setting up a custom password changed notification template.

第1步：创建 templates 目录 #

🌐 Step 1: Create the templates directory

这个示例重用了在 Auth Email Templates – Step 1（volumes/templates）中创建的目录。把你的通知邮件模板添加到这个目录中。

🌐 This example reuses the directory created in Auth Email Templates – Step 1 (volumes/templates). Add your notification email templates to this directory.

你的目录结构应该是这样的：

🌐 Your directory structure should look like this:

1
volumes/
2
  templates/
3
    invite.html
4
    password_changed_notification.html

步骤 2：更新 docker-compose.yml#

🌐 Step 2: Update docker-compose.yml

更新 docker-compose.yml 中的 auth 服务以启用密码更改通知

🌐 Update the auth service in docker-compose.yml to enable password changed notification

docker-compose.yml
1
services:
2
  auth:
3
    depends_on:
4
      db:
5
        condition: service_healthy
6
      templates-server:
7
        condition: service_started
8
    environment:
9
      GOTRUE_MAILER_NOTIFICATIONS_PASSWORD_CHANGED_ENABLED: 'true' # 👈 enabling the notification is required
10
      GOTRUE_MAILER_TEMPLATES_PASSWORD_CHANGED_NOTIFICATION: 'http://templates-server/password_changed_notification.html'
11
      GOTRUE_MAILER_SUBJECTS_PASSWORD_CHANGED_NOTIFICATION: 'Your password was changed'
12
13
  templates-server:
14
    image: caddy:2-alpine
15
    command: ['caddy', 'file-server', '-r', '/templates', '--listen', ':80']
16
    volumes:
17
      - ./volumes/templates:/templates

步骤3：重启容器 #

🌐 Step 3: Restart containers

1
sh run.sh recreate auth templates-server