Test Supabase Auth emails with InboxTap

Choose Mailpit or InboxTap for the job

The Supabase CLI includes Mailpit and exposes its web interface at localhost:54324 by default. Keep that default when a developer mainly needs to inspect local Auth templates by eye.

Choose InboxTap when automated tests benefit from a unique address per case, waitForLink() or waitForCode(), content-safe matchers, deterministic fault rules, or bounded HTML and JSON evidence. This is a testing-workflow choice, not a claim that Supabase lacks local email capture.

• Supabase local Auth email testing ↗

Solve the network topology first

InboxTap binds to the host loopback addresses by default. A Supabase Auth process running inside a container has its own loopback interface, so localhost inside that container is not the InboxTap process on the host.

Configure custom SMTP only in a topology where Auth can reach the listener without broadly exposing an unauthenticated capture service. Do not copy a 0.0.0.0 bind into a shared workstation or CI network. A hosted Supabase project likewise cannot connect to a developer laptop's loopback address.

Test the message after SMTP is connected

Once the chosen local or self-hosted Auth topology can reach InboxTap, create a recipient and trigger signInWithOtp() through the real Supabase client. Despite its name, this method sends a magic link by default; the email template decides whether the user receives a confirmation URL or a code.

Supabase creates a user by default when the address is unknown. Set shouldCreateUser to false when the product permits passwordless sign-in only for an existing account, and seed that account before requesting its message.

The default confirmation link normally contains the Auth verification path shown in the snippet. If the project uses a custom PKCE template or callback endpoint, filter and validate the URL required by that template instead of hard-coding the default.

const inbox = await inboxTap.createInbox({ alias: "supabase-auth" });

const { error } = await supabase.auth.signInWithOtp({
  email: inbox.address,
});

if (error) throw error;

const confirmationUrl = await inbox.waitForLink({
  contains: "/auth/v1/verify",
  timeoutMs: 20_000,
});

• Supabase passwordless email documentation ↗

Respect template and OTP settings

Using the Token variable in a Supabase email template produces an OTP flow, while the confirmation URL produces a link flow. Test the rendered contract rather than inferring it from the client method name.

Supabase allows an email OTP length from six through ten digits. InboxTap's waitForCode() defaults to exactly six digits, so supply a pattern for a configured length. The parsed CapturedEmail.codes convenience array is limited to four through eight digits; a custom waitForCode() pattern scans the body and is the appropriate choice for nine- or ten-digit codes.

• Supabase Auth email-template documentation ↗
• Supabase CLI Auth configuration ↗

Separate local and hosted testing

Supabase's hosted default mail service restricts recipients and rate limits delivery, while hosted custom SMTP expects a network-reachable server with credentials. InboxTap deliberately provides neither public reachability nor SMTP authentication, so it is not a hosted-project SMTP provider.

Use InboxTap for a local or isolated CI environment whose network boundary you control. Use an appropriate authenticated testing or delivery provider when a hosted Supabase project must send over the public network.

• Supabase custom SMTP documentation ↗