Skip to content
Auth

使用自定义 SMTP 发送邮件

如果你正在使用以下配置的 Supabase Auth：

🌐 If you're using Supabase Auth with the following configuration:

  • 电子邮件和密码账户
  • 使用一次性密码或通过邮箱发送的链接（OTP、魔法链接、邀请）的无密码账户
  • 通过 用户页面 或 Auth 管理 API 发送的基于邮箱的用户邀请
  • 通过电子邮件确认的社交登录

你需要搭建一个自定义的SMTP服务器来处理向用户发送消息。

🌐 You will need to set up a custom SMTP server to handle the delivery of messages to your users.

为了让你入门，并探索和设置你应用的电子邮件消息模板，Supabase 为所有项目提供了一个 SMTP 服务器。这个服务器有一些重要的限制，并不适合用于生产环境。

🌐 To get you started and let you explore and set up email message templates for your application, Supabase provides an SMTP server for all projects. This server imposes a few important restrictions and is not meant for production use.

只发送消息到预先授权的地址。

除非你为你的项目配置了自定义 SMTP 服务器，否则 Supabase Auth 将拒绝向不属于项目团队的地址发送消息。你可以在组织设置的 团队选项卡 中管理这个。

🌐 Unless you configure a custom SMTP server for your project, Supabase Auth will refuse to deliver messages to addresses that are not part of the project's team. You can manage this in the Team tab of the organization's settings.

例如，如果你项目的组织有这些成员账户 person-a@example.com、person-b@example.com 和 person-c@example.com，那么 Supabase Auth 只会向这些地址发送消息。其他所有地址都会收到错误信息 Email address not authorized.

🌐 For example, if your project's organization has these member accounts person-a@example.com, person-b@example.com and person-c@example.com then Supabase Auth will only send messages to these addresses. All other addresses will fail with the error message Email address not authorized.

可能随时间变化的显著速率限制。

为了维护默认 SMTP 发送服务的健康和声誉，你的项目可发送的消息数量有限，并且可能会随时更改。目前这个值设置为每小时 2 条消息。

默认 SMTP 服务不保证消息传送或正常运行时间。

默认的 SMTP 服务仅提供尽力而为的支持，适用于以下非生产环境的使用场景：

🌐 The default SMTP service is provided as best-effort only and intended for the following non-production use cases:

  • 探索并开始使用 Supabase 认证
  • 和项目团队的成员一起设置和测试电子邮件模板
  • 搭建玩具项目、演示或任何非关键应用

我们建议所有客户为其他所有使用情况设置自定义SMTP服务器。

🌐 We urge all customers to set up custom SMTP server for all other use cases.

如何设置自定义 SMTP 服务器？ #

🌐 How to set up a custom SMTP server?

Supabase Auth 可以与任何支持 SMTP 协议的邮件发送服务一起使用。首先，你需要选择一个服务，如果还没有账号的话就先注册一个，并获取你账户的 SMTP 服务器设置和凭据。这些包括：SMTP 服务器主机、端口、用户名和密码。你还需要选择一个默认的发件人地址，通常像 no-reply@example.com 这样。

🌐 Supabase Auth works with any email sending service that supports the SMTP protocol. First you will need to choose a service, create an account (if you already do not have one) and obtain the SMTP server settings and credentials for your account. These include: the SMTP server host, port, user and password. You will also need to choose a default From address, usually something like no-reply@example.com.

与 Supabase Auth 配合使用的服务非详尽列表包括：

🌐 A non-exhaustive list of services that work with Supabase Auth is:

一旦你用电子邮件发送服务设置好了账户，就去认证设置页面开启并配置自定义 SMTP。

🌐 Once you've set up your account with an email sending service, head to the Authentication settings page to enable and configure custom SMTP.

你也可以用管理 API 配置自定义 SMTP：

🌐 You can also configure custom SMTP using the Management API:

1
# Get your access token from https://supabase.com/dashboard/account/tokens
2
export SUPABASE_ACCESS_TOKEN="your-access-token"
3
export PROJECT_REF="your-project-ref"
4
5
# Configure custom SMTP
6
curl -X PATCH "https://api.supabase.com/v1/projects/$PROJECT_REF/config/auth" \
7
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \
8
  -H "Content-Type: application/json" \
9
  -d '{
10
    "external_email_enabled": true,
11
    "mailer_secure_email_change_enabled": true,
12
    "mailer_autoconfirm": false,
13
    "smtp_admin_email": "no-reply@example.com",
14
    "smtp_host": "smtp.example.com",
15
    "smtp_port": 587,
16
    "smtp_user": "your-smtp-user",
17
    "smtp_pass": "your-smtp-password",
18
    "smtp_sender_name": "Your App Name"
19
  }'

一旦你保存这些设置，你项目的认证服务器将向所有地址发送消息。为了保护你新设置服务的声誉，系统对每小时消息数设定了较低的限制，为30条。要根据你的使用情况调整到合适的值，请前往速率限制配置页面。

🌐 Once you save these settings, your project's Auth server will send messages to all addresses. To protect the reputation of your newly set up service a low rate-limit of 30 messages per hour is imposed. To adjust this to an acceptable value for your use case head to the Rate Limits configuration page.

应对滥用：如何保持你的 SMTP 服务器的发送信誉？ #

🌐 Dealing with abuse: How to maintain the sending reputation of your SMTP server?

当你让大家知道你的应用并且它越来越受欢迎时，你可能会看到几种滥用情况，这些滥用可能会对你的发送域名的声誉产生负面影响。

🌐 As you make your application known to the public and it grows in popularity, you can expect to see a few types of abuse that can negatively impact the reputation of your sending domain.

滥用的一个常见来源是机器人或攻击者注册你的应用用户。

🌐 A common source of abuse is bots or attackers signing up users to your application.

他们使用已知的邮箱地址列表，用预设的密码为你的项目注册用户。这些行为的规模和强度可能不同：有时候机器人会慢慢地在几个月内发送注册请求，或者一次性发送大量请求。

🌐 They use lists of known email addresses to sign up users to your project with pre-determined passwords. These can vary in scale and intensity: sometimes the bots slowly send sign up requests over many months, or they send a lot of requests at once.

这个行为通常的目标是：

🌐 Usually the goal for this behavior is:

  • 负面影响你的邮箱发送声誉，之后他们可能会要求赎金，承诺停止这种行为。
  • 通过阻止新账户创建、使用魔术链接或一次性密码登录，或者严重影响你应用中的重要安全流程（比如重置密码或忘记密码），来对你的服务造成短期甚至长期的拒绝服务攻击。
  • 为了迫使你降低项目的安全防护，比如通过关闭电子邮件确认。在那之后，他们可能会通过以他人的名义创建账户来针对特定用户或大量用户。然后，他们可以使用社交工程技术欺骗用户以某种方式使用你的应用，让攻击者和受害者都能访问同一个账户。

缓解策略：

🌐 Mitigation strategies:

  • 为你的项目配置 CAPTCHA 保护，这是在这种情况下控制机器人最有效的方法。你可以使用 CAPTCHA 服务，这些服务提供隐形挑战，大多数情况下真实用户不需要解决难题。
  • 在你的应用中，尽量使用社交登录（OAuth）或 SAML 的单点登录，而不是基于邮箱的认证流程。
  • 尽量使用无密码认证（一次性密码），因为这能限制攻击者从这种行为中获取的价值。
  • 不要在压力下关闭电子邮件确认。

额外的最佳实践 #

🌐 Additional best practices

设置并维护 DKIM、DMARC 和 SPF 配置。

与你的电子邮件发送服务合作，为你的发送域配置 DKIM、DMARC 和 SPF。这将显著提高你的邮件送达率。

🌐 Work with your email sending service to configure DKIM, DMARC and SPF for your sending domain. This will significantly increase the deliverability of your messages.

设置自定义域名。

身份验证消息通常包含指向你项目的身份验证服务器的链接。设置自定义域可以减少由于其他 Supabase 项目信誉不佳而导致你的消息被识别为垃圾邮件的可能性。

🌐 Authentication messages often contain links to your project's Auth server. Setting up a custom domain will reduce the likelihood of your messages being picked up as spam due to another Supabase project's bad reputation.

别把身份验证邮件和营销邮件混在一起。

对于身份验证和营销信息，使用不同的服务。如果其中一个的声誉下降，不会影响你的整个应用或运营。

🌐 Use separate services for Auth and marketing messages. If the reputation of one falls, it won't affect your whole application or operation.

这包括：

🌐 This includes:

  • 为了认证使用一个单独的发送域名——auth.example.com，营销则使用另一个域名 marketing.example.com。
  • 使用不同的发件地址——no-reply@auth.example.com 对比 no-reply@marketing.example.com。

准备另一个 SMTP 服务备用。

万一你使用的主要 SMTP 服务出现问题，或者你的账号因为垃圾邮件有被封的风险，你还有其他服务可以使用。

🌐 In case the primary SMTP service you're using is experiencing difficulty, or your account is under threat of being blocked due to spam, you have another service to turn to.

保持品牌一致性并专注内容。

确保你已经把身份验证消息和营销消息分开了。

🌐 Make sure you've separated out authentication messages from marketing messages.

  • 别把促销内容放进验证消息里。
  • 在身份验证信息中避免谈论你的应用是什么。这可能会被自动垃圾邮件过滤器识别为营销内容，从而增加被视为垃圾邮件的可能性。如果你的项目涉及以下内容，这个问题尤其明显：Web3、区块链、人工智能、NFT、赌博、色情。
  • 在身份验证消息中避免使用标语或其他简短的营销内容。
  • 减少身份验证消息中的链接和操作按钮数量。
  • 不要经常更改身份验证消息模板。最好一次性做一个大改动，而不是多次小改动。
  • 避免在认证信息中进行 A/B 测试内容。
  • 在你的营销信息中使用一个单独的基础模板（HTML）。
  • 在认证信息中避免使用电子邮件签名。如果必须使用，确保签名在风格和内容上与营销信息不同。
  • 使用简短明了的主题行。避免或减少主题中的表情符号数量。
  • 减少放在认证消息中的图片数量。
  • 避免在认证消息中包含用户提供的数据，如名称、用户名、电子邮件地址或称呼。如果包含的话，确保对它们进行清理。

提前为大幅增长做好准备。

如果你计划在某个特定时间有大量用户涌入，最好和你的邮件发送服务商合作，调整发送速率限制并相应地管理他们的预期。大多数邮件发送服务不喜欢发送数量突然激增，这可能会影响你的发送信誉。

🌐 If you are planning on having a large surge of users coming at a specific time, work with your email sending service to adjust the rate limits and their expectations accordingly. Most email sending services dislike spikes in the number of messages being sent, and this may affect your sending reputation.

考虑为此类事件实现额外保护措施：

🌐 Consider implementing additional protections for such events:

  • 建立一个排队或候补系统，而不是允许直接注册，这将帮助你控制从邮件发送服务发送的消息数量。
  • 禁用基于邮箱的活动注册，只使用社交登录。或者，你也可以通过在界面上隐藏邮箱注册流程或者让它们更难访问来降低其优先级。

使用发送邮件认证钩子以获得更多控制。

如果你需要对发送过程有更多控制，而不是使用 SMTP 服务器，你可以使用 发送邮件认证钩子。在一些高级场景下，这会非常有用，例如：

🌐 If you need more control over the sending process, instead of using a SMTP server you can use the Send Email Auth Hook. This can be useful in advanced scenarios such as:

  • 你想用 React 或者别的电子邮件模板引擎。
  • 你想使用一个不提供 SMTP 服务的邮件发送服务，或者非 SMTP 的 API 更强大。
  • 你想把消息排队，而不是立即发送，这样可以平滑邮件发送的高峰，或者进行额外的过滤（避免重复消息）。
  • 你想使用多个邮件发送服务来提高可靠性（如果主服务不可用，会自动使用备用服务）。
  • 你想根据邮箱地址或用户数据使用不同的邮箱发送服务（例如，美国的用户用服务A，欧盟的用户用服务B，中国的用户用服务C）。
  • 你想在邮件中添加或包含额外的邮件头，用于跟踪或其他原因。
  • 你想给消息添加附件（通常不推荐）。
  • 你想给消息添加 S/MIME 签名。
  • 你想用一个不对外开放的邮件服务器，比如一些公司或政府的邮件服务器。

延长用户会话时间。

短暂的user sessions可能会对发送邮件造成问题，因为它会迫使活跃用户频繁登录，从而增加需要发送的信息数量。可以考虑延长用户会话的最长持续时间。如果你发现登录次数无缘无故增加，请检查前端应用是否有漏洞。

🌐 Having short lived user sessions can be problematic for email sending, as it forces active users to sign-in frequently, increasing the number of messages needed to be sent. Consider increasing the maximum duration of user sessions. If you do see an unnecessary increase in logins without a clear cause, check your frontend application for bugs.

如果你在前端使用 SSR 框架，并且发现用户登录数量无缘无故增加，检查一下你的设置。确保 @supabase/ssr 包是最新的，并且严格按照我们发布的指南操作。确认你的 SSR 前端的中间件组件按预期工作，并且与我们发布的指南一致。有时候，一个放错位置的 return 或条件判断可能会导致会话提前结束。

🌐 If you are using a SSR framework on the frontend and are seeing an increased number of user logins without a clear cause, check your set up. Make sure to keep the @supabase/ssr package up to date and closely follow the guides we publish. Make sure that the middleware components of your SSR frontend works as intended and matches the guides we've published. Sometimes a misplaced return or conditional can cause early session termination.