Supabase Auth email not received: find where confirmation or magic link stopped

Start with the boundary map

1. Auth request

Capture the flow, project, UTC time, random correlation ID, and client or server error. Signup, invite, recovery, OTP, and magic-link paths can fail differently.

2. Supabase mail path

Determine whether the project uses the built-in SMTP service or custom SMTP. The built-in service is a best-effort development path with recipient and rate restrictions, not a production mail service.

3. SMTP handoff

Read Supabase Auth logs first. Host, port, authentication, template, provider availability, or rate-limit errors belong here.

4. Provider event

After a successful handoff, follow the provider message ID to suppressed, failed, delayed, bounced, or delivered. Provider acceptance is not inbox placement.

5. Receiver visibility

Check spam, quarantine, security gateways, aliases, forwarding, rules, storage, and a trusted original header when a controlled message can be found.

6. Link use

If the message arrived but the link is invalid or expired, investigate token timing and link prefetch separately from mail delivery.

If the project uses Supabase built-in SMTP

Supabase documents its built-in SMTP service as a demonstration path. Without custom SMTP, Auth messages can be sent only to pre-authorized team addresses, the rate limit is deliberately low and may change, and there is no production delivery guarantee. A log such as Email address not authorized identifies that service restriction; it is not evidence of a DNS or receiving-mailbox problem.

• Confirm whether the recipient is a project team address before investigating the receiver.
• Check the current Auth rate-limit settings and logs rather than relying on a remembered numeric limit.
• For production traffic, configure a production SMTP provider and verify the exact From identity it uses.
• Keep Auth and marketing traffic on separate domains or subdomains and separate From addresses so their reputation and incident ownership remain distinct.

If the project uses custom SMTP

Begin in Supabase Auth logs at the request timestamp. A gomail error or an Auth 500 can point to SMTP host, port, credentials, custom-domain settings, provider rate limits, provider downtime, or a malformed email template. Preserve the bounded error and correct that boundary before one controlled retry.

1. Verify the configured SMTP host, port, username, From address, and provider status without exposing the password.
2. Check whether the template rendered successfully. A template failure is an Auth-generation problem, not deliverability.
3. Find evidence that the SMTP provider accepted the same request. If no provider message ID exists, stay at the Supabase-to-provider handoff.
4. Once the provider accepted it, use the provider event trail as the source of truth for suppression, delay, bounce, and receiver acceptance.

If the custom provider is Resend, use the Resend event map to interpret queued, sent, suppressed, failed, delivery_delayed, bounced, and delivered.

Follow provider and receiver evidence

For a suppression, failure, delay, or bounce, preserve the exact provider reason and complete SMTP diagnostic when available. Separate temporary 4xx deferrals from permanent 5xx failures and keep the enhanced status code. Decode the SMTP reply locally before changing DNS or retry policy.

If the provider reports delivered, move to receiver visibility. Search the mailbox's own interface, quarantine, spam or junk, category tabs, rules, aliases, forwarding, storage, and corporate security gateways. A controlled original header can show trusted receiver timestamps and authentication results; analyze it locally without uploading the pasted header.

If the email arrived but the link fails

This is a different incident. Supabase documents that email-security scanners and link-preview systems can prefetch a confirmation or magic link before the user opens it. Correlate the Auth API response, an otp_expired log, timestamps, and source IPs. A 403 or expired-token event after the message arrived does not mean SMTP delivery failed.

• Keep confirmation and recovery tokens short-lived and single-use according to the application's security model.
• Do not disable email confirmation or weaken token security as a delivery workaround.
• Use a controlled test account to distinguish link prefetch from a genuinely late user action.
• Invalidate duplicate secrets when a controlled resend is necessary.

The first ten minutes

1. Record the Auth flow, UTC time, project, affected scope, and bounded client or server error.
2. Read Supabase Auth logs and identify built-in SMTP, custom SMTP, template, rate-limit, or handoff evidence.
3. If custom SMTP accepted the message, follow its provider ID to the latest event. Do not create parallel retries while the first message is delayed.
4. If the receiver accepted it, check private filtering and obtain a controlled original header when possible.
5. If the email arrived but its link failed, correlate otp_expired, API status, timestamp, and prefetch evidence as a token-use incident.

A safe incident packet

Application

Flow, project reference, UTC time, template version, random correlation ID, and bounded client or server error.

Supabase

Auth log timestamp and category, built-in or custom SMTP path, handoff result, and bounded diagnostic. Exclude tokens and project secrets.

Provider

Provider message ID, ordered event names and timestamps, and bounded suppression, delay, or bounce reason.

Receiver

Affected domain and scope, quarantine or rule evidence, and a controlled original header when available.

Link use

API status, otp_expired timestamp, user-action time, and bounded prefetch evidence without the URL or token.

Next action

The first unproven boundary, owner, one corrective action, and the condition for one controlled retry.

Inventory the Auth sending path locally so From domain, provider, owner, DKIM identity, Return-Path, receiver evidence, and fallback responsibility remain visible before an incident.