Supabase Auth And Sendgrid Setup: Custom Smtp Guide

When you build an app with Supabase Auth, your users expect instant confirmation emails, reliable password resets, and clean magic links. Out of the box, Supabase provides a built-in mailer for quick testing. However, that default mailer enforces strict hourly limits and sends emails from shared infrastructure, which frequently triggers spam filters. Connecting an external provider fixes these deliverability bottlenecks.

Configuring Supabase Auth with SendGrid routes all transactional and marketing emails through a dedicated mail stream. This guide walks you through setting up SendGrid SMTP credentials within Supabase, configuring DNS authentication records, handling template variables, and debugging common delivery failures.

Why Switch from Default Supabase Mail to SendGrid

The default Supabase email service works fine for local prototyping, but production apps outgrow it quickly. Supabase limits default project emails to prevent abuse, meaning high-volume signups will experience delayed or dropped messages.

SendGrid provides reliable infrastructure designed for scale. Routing authentication emails through SendGrid gives you delivery analytics, suppression management, and control over sender reputation. Furthermore, pairing Supabase authentication with SendGrid allows you to synchronize new user records directly into your marketing contact lists using webhooks or edge functions. Additional reporting by Bloomberg delves into related views on the subject.

Step 1: Gather Your SendGrid SMTP Credentials

Before touching your Supabase dashboard, you need to generate and record your SMTP relay details from SendGrid.

1. Log into your SendGrid account and navigate to Settings > API Keys. Create a key with restricted permissions, or use a dedicated SMTP relay credential.
2. Go to Settings > Sender Authentication and complete domain authentication (SPF and DKIM). Skipping this step guarantees your emails will land in spam folders.
3. Note down your connection parameters:
   • Host: smtp.sendgrid.net
   • Port: 587 (or 465 for SSL)
   • Username: apikey (this is a literal string for SendGrid, not your email account username)
   • Password: The actual API key or SMTP password generated by SendGrid

Step 2: Configure Custom SMTP in Supabase

With your SendGrid credentials ready, point your Supabase project to the new mail relay.

1. Open your Supabase project dashboard and click Authentication in the left sidebar.
2. Scroll down to the Configuration section and select Emails.
3. Click on the SMTP Settings tab.
4. Toggle Enable Custom SMTP to on.
5. Fill out your sender details:
   • Sender Email: Must match a verified sender identity or domain inside SendGrid.
   • Sender Name: The public-facing name users see in their inbox (e.g., "Your App Team").
6. Enter the SendGrid parameters you gathered:
   • Host: smtp.sendgrid.net
   • Port: 587
   • Username: apikey
   • Password: Your SendGrid API key
7. Click Save. Supabase will test the connection string against your provided host.

Step 3: Customize Auth Templates and Variables

Supabase uses Go template syntax for its authentication emails. Once custom SMTP is active, you can edit these templates directly under Authentication > Emails > Templates.

Common templates include confirmation signups, magic links, password resets, and email changes. Each template relies on specific variables supplied at runtime:

• {{ .ConfirmationURL }}: The unique link required to verify a new user signup.
• {{ .Token }}: The numeric or alphanumeric one-time password (OTP) code.
• {{ .SiteURL }}: Your main application URL configured in project settings.
• {{ .Email }}: The recipient user's email address.

When writing custom HTML templates, avoid complex external stylesheets. Keep your layouts single-column, inline critical CSS, and always include a plain-text fallback link at the bottom so users can copy and paste URLs if their email client strips buttons.

Step 4: Handle Email Prefetching and Security Scanners

Modern corporate email clients and security software use automated link prefetchers. When an email arrives, these scanners automatically click links to check for malicious content. If a scanner clicks your {{ .ConfirmationURL }} before the user does, the token gets consumed, leaving the user with an "expired token" error.

To mitigate prefetching issues, consider these adjustments:

• Switch high-risk flows to use a 6-digit Email OTP ({{ .Token }}) combined with a manual input form on your frontend.
• Construct a custom verification page that requires an explicit button click or POST request rather than a direct GET action on token consumption.

Common Setup Mistakes and Troubleshooting

Even with correct credentials, small configuration errors can block mail delivery.

If Supabase throws a 500 error when triggering an auth email, check your SMTP username. A common mistake is entering your personal SendGrid login email instead of the literal string apikey.

If emails arrive successfully but lack branding or show generic sender warnings, verify that your SendGrid domain authentication records (CNAMEs for DKIM) are correctly propagated in your DNS provider. Without DKIM and SPF alignment, inbox providers flag external mailers as suspicious.

Finally, review your Supabase rate limits under Authentication > Rate Limits. Ensure your hourly caps align with your SendGrid pricing tier to prevent dropped messages during traffic spikes.

Frequently Asked Questions

Why can't I edit Supabase email templates on a new project?

Supabase restricts dashboard template editing on newer free-tier projects until you configure a custom SMTP provider. Setting up SendGrid unlocks the template editor immediately.

What port should I use for SendGrid SMTP?

Port 587 with STARTTLS is the standard recommendation for modern web applications. Port 465 works for implicit SSL, but 587 handles connection handshakes more reliably across various cloud environments.

How do I sync Supabase users into SendGrid marketing lists?

While SMTP handles transactional mail, marketing contacts require a separate synchronization step. You can set up a Supabase Database Webhook or a backend Edge Function that triggers upon row creation in auth.users, automatically adding new signups to your SendGrid marketing contact lists via the SendGrid API.

Can I test auth emails locally before deploying?

Yes. If you run Supabase locally via the CLI, auth emails aren't sent through SendGrid by default. Instead, they route to a local mail pit server where you can inspect rendered templates and variables safely without spamming real inboxes.