Authentication emails

TurboStarter provides a set of preconfigured authentication emails that you can use to send emails to your users (including magic link, reset password etc.).

To know when any of these emails need to be sent, we're using Auth hooks, which is a native Supabase Auth feature.

The full process of recognizing which email should be sent is fully implemented for you, the only thing that you need to do is to define an auth hook and configure secret for it in your Supabase project.

Not configuring the hook will result in users not being able to verify their email address or signing into the app.

Send email hook

To send authentication emails to your users, you will need to configure a send_email hook in your Supabase project.

Go to the Supabase Dashboard.
Click on the project you want to use.
Go to the Authentication tab.
Click on Hooks and then on Add hook.
Choose Send email as a hook type and configure it with the following settings:

Auth hook configuration

Hook type: Pick HTTPS, as we want to call our API endpoint to send the email.
Url: Add your web app url with the webhook path at the end. The webhook path is /api/webhooks/auth/email. If your app is hosted at https://myapp.com then you need to enter https://myapp.com/api/webhooks/auth/email as the URL.
Secret: Generate a secret and save it for later use.

Set copied secret as an environment variable in your project. That way we can validate if the request is coming from your project not from some other project.
SEND_EMAIL_HOOK_SECRET="your-copied-secret"

Omit prefix in environment variable

When setting up the environment variable value, please omit v1,whsec_ prefix from the secret you copied. It's used to define the type of secret, but it's not needed to validate the request.

So, when your secret is v1,whsec_1234567890 you should set SEND_EMAIL_HOOK_SECRET="1234567890" in your project.

That's it! You've configured the send_email hook and can now send authentication emails to your users. Remember that you can always modify its configuration from the Supabase dashboard.

Auth hook configured

Local development

We're using the same mechanism in local development with local Supabase instance. You don't need to setup anything extra, it will be up and running with your development server.

For curiosity, you can find the hook setup in packages/db/supabase/config.toml file:

config.toml

[auth.hook.send_email]
enabled = true
uri = "http://host.docker.internal:3000/api/webhooks/auth/email"
secrets = "env(SEND_EMAIL_HOOK_SECRET)"

As you can see, we're also protecting the endpoint with the secret, just make sure that the same secret is used for Supabase side (in packages/db) and to validate the payload (in apps/web).

Auth Hooks

supabase.com

Send Email Hook

supabase.com

Send email hook

Local development

Auth Hooks

Send Email Hook

On this page