Supabase "Error sending confirmation email" (500): what it means and the 6 causes

When a new user signs up with Supabase Auth and the expected confirmation email fails to be sent, the app displays an Error sending confirmation email with a 500 server error code. This error message alone does not provide any specific details on the root cause. To identify the underlying issue, you need to examine the Auth logs within your Supabase dashboard.

The error can stem from various factors, and each cause leaves a distinct line in the logs for troubleshooting. Begin by checking the SMTP provider mentioned in the logs. If the line mentions a connection issue, sender problem, or certificate error, refer to cause 2 or 3 for potential solutions. If the logs reveal a database object, trigger, or relation as the culprit, the problem lies within the database.

If you are using the default email service, remember that Supabase Auth will not deliver messages to addresses outside the project's team. Ensure that the email address being tested is part of the project's team, as every new stranger is not included. To resolve this, switch to an alternative email provider such as Resend, AWS SES, Postmark, Twilio SendGrid, ZeptoMail, or Brevo.

Once you have chosen a provider, copy the SMTP host, port, username, and password from the provider's SMTP page. Enable custom SMTP in the Supabase Authentication settings and enter these values. Sign up with a new address that is not part of your team to verify the fix.

Another possible cause is misconfiguration of custom SMTP settings. Compare the Supabase-provided SMTP values (host, port, username, password, and sender address) with the information obtained from your email provider. Ensure the sender address is valid and allowed by the provider. Update the Supabase SMTP settings accordingly and test the sign-up process again.

If the sender domain has not been verified with your email provider, add the provider's DNS records to your domain's DNS host. This process typically involves adding SPF, DKIM, and DMARC records. Once the domain is verified, set up the sender address in the Supabase SMTP settings to ensure successful email delivery.

In some cases, a Send Email hook may fail to respond within the allocated time, resulting in the hook_timeout error. If you are using a Send Email hook for authentication emails, verify that the hook's endpoint or function is active and reachable. Review the hook's logs for any errors or slow responses at the time of the failure. If the issue persists, consider switching back to SMTP sending.

Another potential issue is reaching the sending limit imposed by Supabase. When a limit is the cause, the error message typically reads "email rate limit exceeded" with a status code of 429. For custom SMTP configurations, you can raise the message limit on the Rate Limits page within the Authentication section of your Supabase dashboard.

Lastly, if none of the above causes apply, Supabase Auth itself may be experiencing a degradation. In this scenario, the Auth logs will not show any provider or database errors. Check Supabase's system status page for any ongoing incidents, and wait for the resolution before attempting to sign up with a new address.