Three of the starter's six auth screens send email: sign-up confirmation, magic link, and password recovery. All three go through Supabase's email service, which needs configuring before it is usable for anything but development.

Custom SMTP

Templates

Authentication → Email Templates. Each one is HTML with Go template variables.

The OTP code

The starter's /verify-otp screen asks for a six-digit code, and the magic-link screen sends the user there. That code only exists in the email if the template includes {{ .Token }} — the default Magic Link template has the link but not the code.

Add both, so either path works:

Copy<h2>Sign in to My App</h2>
 
<p><a href="{{ .ConfirmationURL }}">Click here to sign in</a></p>
 
<p>Or enter this code: <strong>{{ .Token }}</strong></p>
 
<p>It expires in an hour. If you did not request this, ignore this email.</p>

Offering both matters more on mobile than on web: a mail client that opens the link in an in-app browser can fail to hand control back to your app, and the code is the escape hatch.

Deep links

The link in an email has to come back into the app. Two things make that work.

The redirect passed from the client. The starter uses makeRedirectUri(), which resolves to exp://… in Expo Go and <scheme>:// in a build:

Copyconst redirectTo = makeRedirectUri();
 
await supabase.auth.signUp({
  email,
  password,
  options: { emailRedirectTo: redirectTo },
});

Password recovery adds a path, so the user lands on the right screen:

Copyconst redirectTo = makeRedirectUri({ path: 'reset-password' });
 
await supabase.auth.resetPasswordForEmail(email, { redirectTo });

The allow-list. Supabase rejects any redirect target not in Authentication → URL Configuration → Redirect URLs:

exp://localhost:8081
exp://localhost:8081/--/reset-password
my-app://
my-app://reset-password

The /--/ spelling is how Expo Go encodes a path. Include it or password recovery works in a build and not in development.

Once the app has the URL, providers/auth-provider.tsx exchanges it for a session — see authentication.

Confirmations on or off

supabase/config.toml has confirmations off locally:

Copy[auth.email]
enable_confirmations = false

So signUp returns a session immediately and you are not clicking through a mail catcher on every reload. The hosted project has them on by default, which is right for production — and it changes what signUp returns:

Copyif (!data.session) {
  toast.success('Check your email', `We sent a confirmation link to ${email}.`);
  router.replace('/sign-in');
}

That branch is why the sign-up screen does not look broken when confirmations are on. Keep it.

Testing locally

supabase start includes Inbucket, which catches every message the stack sends instead of delivering it. The whole flow — sign-up, magic link, OTP, recovery — is testable with no SMTP configured at all.

pnpmnpmyarnbun
pnpm dlx supabase start
# then open http://localhost:54324
Copy

Emails appear immediately, with the rendered template, so it is also the fastest way to check that {{ .Token }} is where you think it is.

Rate limits and abuse

Email endpoints are the ones people hammer. Supabase applies per-hour limits per address and per IP, and the starter surfaces the resulting error in a toast rather than swallowing it.

Two behaviours worth knowing:

• resetPasswordForEmail returns success whether or not the address has an account, so the form cannot be used to discover who has one. The starter's confirmation copy says "if an account exists" for the same reason.
• signInWithOtp in the starter passes shouldCreateUser: false, so the magic link screen cannot create accounts by accident. Flip it if you want magic links to double as sign-up.

When it does not work

Next

• Authentication
• Troubleshooting
• Supabase SMTP docs