setting-up-supabase-auth-emails

设置 Supabase 身份验证邮件

Supabase 会为每封身份验证邮件调用 PostHog 的 Send Email Hook。Supabase 的操作由用户手动完成，因此请准确告知他们要点击什么，并按以下顺序进行。

如果已连接 Supabase MCP 服务，请使用它读取项目 URL（步骤 4）和日志（Hook 调用失败时）。它没有用于身份验证设置的工具。即使你可以访问其他 Supabase 功能，也应将 Hook 和速率限制留给用户设置，因为这些设置会发送每封注册邮件。

这些工具受 Beta 标志控制。如果 supabase-auth-emails-settings-get 不可用，请告知用户该功能尚未为其项目启用，然后停止。

设置

1. 读取当前状态。 调用 supabase-auth-emails-settings-get。保留 hook_url、email_types 列表和当前的 templates 映射。如果项目已完成设置，只更改用户要求的内容。
2. 一次性询问用户的选择。 在进行任何更改前，一并询问以下问题。如果客户端有多选题工具，请使用该工具。跳过步骤 1 的状态已回答的问题。
   • 项目： 如果没有 Supabase MCP，请询问项目的 Supabase 控制台链接（supabase.com/dashboard/project/<project-ref>）。
   • 模板： 创建 PostHog 入门模板，还是使用用户已有的模板。
   • Hook 密钥： 粘贴到聊天中，还是由用户在 PostHog 中输入。
3. 检查邮件发件方。 模板需要一个已验证发件域名的邮件渠道。按照 building-workflows 技能入门参考中的设置检查步骤操作。
4. 保存项目 URL。 使用 Supabase MCP 时，调用 get_project_url。否则，URL 为 https://<project-ref>.supabase.co。对于自托管项目或自定义域名，请向用户询问其应用用于访问 Supabase Auth 的 URL。使用 supabase-auth-emails-settings-update 保存该 URL。
5. 让用户在 Supabase 中创建 Hook，并保持关闭状态。 Hook 启用期间，任何 Hook 故障都会导致用户注册或密码重置失败。向用户提供 hook_url 和以下步骤：
   • 打开 Authentication > Hooks，添加 Send Email Hook，并选择 HTTPS。
   • 将 Hook URL 粘贴为端点。
   • 点击 Generate secret，并复制完整值。
   • 保持 Enable Send Email hook 关闭，然后保存。
6. 保存 Hook 密钥。 绝不要编造 Hook 密钥。如果已保存密钥，请不要在请求中包含 hook_secret，以保留现有密钥；如需替换，先征求用户同意。绝不要传入空值，因为空值会清除密钥。
   • 在聊天中： 使用 supabase-auth-emails-settings-update 保存密钥。回复时不要再次提及该密钥。
   • 在 PostHog 中： 向用户提供其 PostHog 应用中的 /workflows/channels?setup=supabase 链接。该链接会打开 Supabase 设置。用户粘贴密钥并点击 Save connection。然后调用 supabase-auth-emails-settings-get，确认 has_hook_secret 为 true。
7. 根据用户在步骤 2 中的选择映射模板：
   • 入门模板。 调用 supabase-auth-emails-starter-templates-create。对于每种 has_starter_template 为 true 且尚无可用模板的邮件类型，该工具都会创建并映射一个模板。如果因发件域名未验证而失败，请返回步骤 3。若要修改模板文案或样式，请使用 designing-email-templates 技能。
   • 现有模板。 使用 workflows-list-email-templates 列出模板，保留标记为事务性且敏感的模板，并询问用户每封邮件要使用哪个模板。既非事务性也非敏感的模板目前无法映射。将模板设为事务性前请先征求用户同意，因为此操作无法撤销。使用 supabase-auth-emails-settings-update 提交映射。由于该字段会替换整个映射，请基于步骤 1 中的映射合并更改后构建 templates。取消已有模板映射前请先征求用户同意。
8. 在启用 Hook 前检查。 在最近一次调用的响应中，确认已设置 supabase_url、has_hook_secret 为 true，并且步骤 1 的 email_types 列表中每种核心邮件类型都有模板。写入操作的响应不会包含该列表。核心类型是不以 _notification 结尾的类型。没有模板的核心类型会导致用户的操作失败。没有模板的通知类型会被跳过。
9. 让用户启用 Hook。 在 Supabase 中编辑 Send Email Hook，开启 Enable Send Email hook，然后保存。PostHog 无法检测 Hook 是否已开启，因此 Supabase 卡片上的 Connected 状态仅表示连接已保存。
10. 让用户提高 Supabase 的邮件速率限制。 Supabase 会先检查自身的每小时邮件限制，再调用 PostHog。内置邮件发送器每小时最多允许发送 2 封邮件。Hook 开始发送邮件后，用户可以在 Authentication > Rate Limits 下提高限制。请让用户检查该处的数值。
11. 进行测试。 请用户邀请一位用户（Authentication > Users > Add user > Send invitation），或请求密码重置，并使用一个他们能查看的邮箱地址。邮件应通过映射的模板发送。 只有在用户确认测试邮件已送达后，才能报告完成。注明你没有配置模板的任何邮件类型。

要断开连接，用户应先在 Supabase 中关闭钩子，然后在 PostHog 设置窗口中点击 Disconnect。如果顺序相反，中间所有身份验证邮件都会发送失败。

钩子调用失败时

用户可以在 Supabase 中查看这些信息：在应用的错误提示中，或在 Logs > Auth 下。使用 Supabase MCP 时，在询问用户之前，先用它的 query_logs 工具自行查找失败的调用。该工具会读取 Supabase 的日志。PostHog 的 query-logs 工具无法查看这些日志。

Supabase 中显示的内容	原因	修复
"email rate limit exceeded"	Supabase 自身的每小时限制。PostHog 从未收到该调用。	提高限制（步骤 10）。
Supabase 的通用钩子错误，并显示钩子返回 401	钩子密钥不匹配。	让用户重新复制完整密钥，并使用 supabase-auth-emails-settings-update 保存。
"No PostHog template is set for the ... email."	某种核心邮件类型没有模板。	配置映射（步骤 7）。
"We couldn't send your email. Try again in a few minutes."	未保存项目 URL、映射的模板已删除或不再属于事务性和敏感邮件、未验证发件人、邮件配额已用尽，或发送速度过慢。	检查设置和每个映射的模板。如果都正常，请重试。
邮件中的链接指向错误位置	项目 URL 不正确。	保存正确的 URL。