Supabase’s local testing documentation says test emails are captured instead of being sent to external inboxes. (Supabase’s local email testing guide) So first identify the environment: check the local mail viewer during local development; for a hosted project, check sending configuration, recipient eligibility, and Auth logs. If the test must prove delivery to a real inbox, run it from your own product’s staging environment. A captured local message is not proof of external delivery.
This week’s action: label each failing test as local capture, hosted-project sending, or external delivery before triggering it again.
Developers building Supabase Auth signup confirmation or email login can use this guide to separate captured messages from real inbox tests.
QA teams can use it to identify the failing layer and record reproducible evidence.
Independent developers and release owners can use it to review SMTP configuration and define what must pass before launch.
Developers: distinguish captured mail from external delivery
Local development and hosted projects behave differently. A local Auth action can generate a message that appears in the local mail viewer without sending anything to the recipient’s public inbox. That is useful for checking whether the application triggered the expected email, but it says nothing about external delivery.
Where should you look for a confirmation email sent during local Supabase Auth testing? Open the local email capture interface used by your Supabase development setup and locate the message there. The official local testing documentation explains that local test messages are captured rather than actually sent. Check the captured message’s recipient, subject, rendered body, and link before concluding that the local flow worked.
If there is no captured message, check whether the test action reached Auth at all. Confirm that the user action ran against the intended local project, then inspect the app’s response and relevant Auth logs. A missing message in the capture interface may indicate that the trigger failed, that the app is pointing to another environment, or that the request failed before message generation. Repeating the same click without recording the response usually adds little diagnostic value.
| Test target | Suitable environment | What a pass demonstrates | What it does not demonstrate |
|---|---|---|---|
| Template wording and layout | Local capture | Auth generated a message with the content available for review | External sending or inbox placement |
| Confirmation URL or token handling | Local capture, with the app configured for that flow | The captured message contains the expected verification material and the app can process the test path | Delivery to a real mailbox |
| External receipt and sender identity | A hosted staging project configured for external sending | The tested message reached the chosen external test inbox under that configuration | A universal delivery rate or guaranteed future placement |
Why didn’t the Supabase Auth test email arrive in a real mailbox? If the action ran against the local development environment, the expected result may be capture rather than external delivery. If it ran against a hosted project, check whether the project is using its default sending service or configured custom SMTP, and whether the test recipient is permitted under the current sending rules.
QA: match evidence to the test objective
A test can pass one email-related requirement and fail another. QA should state which requirement is under test before choosing a mailbox or environment. This prevents a rendered template from being mistaken for a completed confirmation flow, or a received message from being mistaken for a successful redirect.
For template review, inspect the captured or delivered message for the expected subject, wording, branding, and dynamic content. For a confirmation-flow assertion, follow the link or use the relevant token in the test application, then verify the resulting account state and page. For a real-receipt test, send from an environment configured to deliver externally and inspect the destination inbox.
The Supabase email template documentation describes how Auth email templates use dynamic values. Compare the template with the actual message rather than checking only the template editor: a correct-looking template does not prove the triggered message contained the intended values.
How can QA confirm that a Supabase Auth email was handed to a sending service? Check the hosted project’s Auth logs for the request and its error or status details, then compare that evidence with the configured sending path. A successful-looking application response alone does not prove that a recipient’s mailbox accepted or displayed the message. Record the log evidence alongside the environment and recipient used.
For every reproducible case, record:
- Environment: local, staging, or production.
- Project and Auth action: for example, signup confirmation or password recovery.
- Trigger: the exact action or test step that requested the message.
- Recipient: use a test inbox approved for that environment.
- Evidence: application response, relevant Auth log details, captured message or delivered message, and the resulting page or account state.
For privacy, use a dedicated test recipient rather than a colleague’s personal mailbox. Avoid putting real customer data into test accounts or screenshots. If your team needs a longer-term address arrangement, review the differences between a temporary address and email forwarding for a stable inbox; the right choice depends on whether the test needs a disposable destination or ongoing receipt. For a test address that needs to remain associated with an account, compare the options in this guide to choosing an email address before using a disposable inbox.
Project maintainers: check restrictions before changing SMTP
A hosted project’s sending behavior depends on its configuration. Supabase documents restrictions for its default email sending service and supports configuring custom SMTP. Those rules can change, so check the current Auth SMTP documentation before treating a recipient rejection as a product bug or relying on a remembered limit.
| Sending path | First check | Appropriate use | Common misunderstanding |
|---|---|---|---|
| Default hosted sending service | Current recipient eligibility and service restrictions in Supabase documentation | Initial checks where the current project rules permit the intended test | Assuming every arbitrary test address is eligible |
| Configured custom SMTP | SMTP host, credentials, sender details, and the service’s own acceptance or rejection evidence | Staging or production-like tests that need an external sending path | Treating SMTP configuration as proof that the destination inbox received the message |
| Local capture | Local project configuration and the capture interface | Development checks for generated content and local flow behavior | Treating a captured message as an externally sent message |
What should you do if a Supabase Auth project says the recipient address isn’t authorized? First check which project and sending service handled the request. Then compare the recipient with the current documented restrictions for that service. If the test needs a recipient outside the permitted scope, configure an appropriate custom SMTP service for your own staging project or choose an authorized test address. Do not keep retrying an address the project is not allowed to send to.
Next, inspect the Auth logs and preserve the exact error. Supabase’s Auth error-code reference and troubleshooting guide for missing Auth emails help distinguish configuration and request failures from later delivery problems. The key question is where the evidence stops: before the project attempts sending, during handoff, or after the sending service accepts the message.
A project-side failure means the request may not have been handed to the configured service. If logs show a sending attempt or handoff, that still does not establish that the recipient provider accepted the message, placed it in the inbox, or avoided the spam folder. Continue with the SMTP service’s evidence and the destination mailbox’s folders. Do not generalize from one test recipient to every provider or future message.
Developers: validate template variables and redirect behavior
The email can be generated correctly while its confirmation path is wrong. Check the message body and the application destination as separate parts of the test. Verify that the template uses the appropriate dynamic values for the intended Auth action, then open the resulting link and confirm that the app handles the response as expected.
Supabase’s local email template guidance covers local template customization. For hosted Auth, the email template documentation is the relevant reference for template behavior. Compare the actual message with the template configuration; do not assume that a template preview reproduces every runtime value.
What if the confirmation link opens the wrong page or fails? Check the redirect target in the message first. Then verify that the intended URL is permitted by the project’s redirect configuration and that the application handles the returned Auth state. Supabase documents redirect behavior and allowed URLs in its redirect URL guide. A generated link is not a passed end-to-end test until the app reaches the expected state.
Keep the failure classification narrow. A missing message is not automatically a redirect problem. A link that opens the wrong page is not evidence that SMTP failed. Capture the message and the final browser destination separately so the owner of the template, project configuration, or app callback can investigate the relevant layer.
Release owners: require real receipt only when the release claim needs it
Local capture is sufficient when the release check is limited to content generation or a local application flow. It is insufficient when the release claim includes receipt at an external inbox, the configured sender identity, or the complete end-user journey. Those checks require an external sending path in a suitable staging environment.
Before calling the test complete, confirm that the staging project uses the intended sending configuration and an approved test recipient. Trigger the same Auth action the user will take. Record whether the message appeared, where it appeared, and whether the confirmation link led to the expected application state. Review the project’s Auth evidence and any available sending-service evidence. A single successful test is evidence about that test, not a general delivery-rate guarantee.
A practical release rule is:
- If the requirement is message generation, inspect the local capture or staging message.
- If the requirement is confirmation-flow behavior, test the link or token and verify the resulting application state.
- If the requirement is external receipt or sender identity, use a hosted environment configured for external sending and inspect the actual destination inbox.
Triage by symptom, not by repeated retries
Use this checklist before running another test:
- [ ] Confirm whether the app points to the local project or a hosted project.
- [ ] For local testing, check the local capture interface before searching an external inbox.
- [ ] Confirm that the intended Auth action actually ran and record its response.
- [ ] For hosted sending, identify the configured sending service and check whether the recipient is eligible.
- [ ] Inspect Auth logs for the exact request and error evidence.
- [ ] If the service accepted the message, check the destination inbox and spam folder.
- [ ] If the message arrived but the flow failed, inspect the template values, redirect allowlist, and application callback handling.
- [ ] Repeat only after recording the changed condition and expected result.
| Symptom | First owner | First evidence to inspect | Next check |
|---|---|---|---|
| No message in local capture | Developer | Project target, trigger response, local Auth evidence | Confirm the test reached the intended local project |
| Hosted project rejects the recipient | Project maintainer | Auth error and current sending restrictions | Use an eligible recipient or configure suitable staging SMTP |
| Sending appears to have been handed off, but no inbox message is visible | Project maintainer or QA | Auth logs and sending-service evidence | Check the destination folders and the service’s delivery records |
| Message arrives, but the link fails or lands incorrectly | Developer | Message URL and browser destination | Review allowed redirects and application callback behavior |
The most useful handoff between teams is a short evidence bundle: environment, action, recipient, exact error or log entry, message artifact, and final redirect result. That lets the next owner distinguish a trigger problem from a sending restriction, a delivery issue, or a broken application route without guessing.
For a real external-receipt check on your own product, a temporary test inbox can be one option when the test does not require a long-lived account or replies. SendTmp offers an instant inbox without registration, so QA can keep a short-lived test destination separate from a primary mailbox and avoid adding test messages to its regular inbox. Use it only where the test’s retention and recovery needs fit; important accounts that require long-term access should use a stable, team-controlled address instead.