setting-up-supabase-auth-emails

Supabase 認証メールの設定

Supabase は認証メールごとに、PostHog の Send Email Hook を呼び出します。Supabase の手順はユーザー自身が手動で行うため、クリックする場所を正確に伝え、以下の順序を守ってください。

Supabase MCP サーバーが接続されている場合は、それを使ってプロジェクト URL（ステップ 4）とログ（フック呼び出しに失敗した場合）を確認してください。Auth 設定用のツールはありません。ほかの Supabase アクセス権がある場合でも、すべてのサインアップメールの送信に関わる設定のため、フックとレート制限の設定はユーザーに任せてください。

ツールはベータフラグで管理されています。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 のスターターテンプレートを作成するか、すでにあるテンプレートを使うかを尋ねます。
   • フックシークレット： チャットに貼り付けるか、ユーザー自身が PostHog に入力するかを尋ねます。
3. メール送信元を確認します。 テンプレートには、送信ドメインが検証済みのメールチャネルが必要です。building-workflows スキルのオンボーディングリファレンスにあるセットアップ確認に従ってください。
4. プロジェクト URL を保存します。 Supabase MCP がある場合は、get_project_url を呼び出します。ない場合は https://<project-ref>.supabase.co です。セルフホストのプロジェクトまたはカスタムドメインの場合は、アプリが Supabase Auth に接続する際に使用する URL をユーザーに尋ねます。supabase-auth-emails-settings-update で保存します。
5. Supabase でフックをオフのまま作成してもらいます。 フックがオンの間にフックの呼び出しが失敗すると、ユーザーのサインアップまたはパスワードリセットも失敗します。hook_url と以下の手順を案内します。
   • Authentication > Hooks を開き、Send Email フックを追加して、HTTPS を選択します。
   • フック URL をエンドポイントとして貼り付けます。
   • Generate secret をクリックし、値全体をコピーします。
   • Enable Send Email hook はオフのままにして、保存します。
6. フックシークレットを保存します。 フックシークレットを捏造してはいけません。すでにシークレットが保存されている場合は、保持するために 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 が設定されている各メールタイプについて、テンプレートを作成してマッピングします。送信元が未検証で失敗した場合は、手順 3 に戻ります。テンプレートの文面やスタイルを変更するには、designing-email-templates スキルを使用します。
   • 既存のテンプレート： workflows-list-email-templates で一覧表示し、トランザクション用で機密扱いとしてマークされているものを残して、各メールの送信に使うテンプレートをユーザーに尋ねます。どちらにも該当しないテンプレートは、まだマッピングできません。トランザクション用にすると元に戻せないため、その変更を行う前にユーザーに確認します。supabase-auth-emails-settings-update でマッピングを送信します。templates フィールドはマッピング全体を置き換えるため、手順 1 のマッピングに変更を反映して templates を作成してください。現在送信に使われているテンプレートのマッピングを解除する前に、ユーザーに確認します。
8. フックを有効にする前に確認します。 最後の呼び出しのレスポンスで、supabase_url が設定されていること、has_hook_secret が true であること、手順 1 の email_types リストにあるすべてのコアメールタイプにテンプレートがあることを確認します。書き込み操作のレスポンスには、このリストは含まれません。コアタイプとは、名前が _notification で終わらないタイプです。テンプレートがないコアタイプでは、ユーザーの操作が失敗します。テンプレートがない通知はスキップされます。
9. ユーザーにフックを有効にしてもらいます。 Supabase で Send Email フックを編集し、Enable Send Email hook をオンにして保存してもらいます。PostHog ではフックがオンかどうかを確認できないため、Supabase カードの Connected ステータスは、接続が保存されていることだけを示します。
10. Supabase のメールレート制限を引き上げてもらいます。 Supabase は PostHog を呼び出す前に、独自の時間あたりのメール送信上限を確認します。組み込みメーラーの上限は 1 時間あたり 2 通です。フックからメールを送信するようになったら、ユーザーは 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）。
フックからの 401 を含む Supabase の一般的なフックエラー	フックのシークレットが一致していません。	ユーザーにシークレット全体をもう一度コピーしてもらい、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 を保存します。