Email Configuration in the Next.js Supabase SaaS Starter Kit

Configure Nodemailer (SMTP) or Resend to send transactional emails from your Next.js Supabase application. Learn the difference between MakerKit emails and Supabase Auth emails.

MakerKit uses the @kit/mailers package to send transactional emails like team invitations and account notifications. You can choose between Nodemailer (any SMTP provider) or Resend (HTTP API).

MakerKit vs Supabase Auth Emails

Before configuring your email provider, understand the two email systems in your application:

Email Type	Purpose	Configuration	Examples
MakerKit Emails	Application transactional emails	Environment variables	Team invitations, account deletion, OTP codes
Supabase Auth Emails	Authentication flows	Supabase Dashboard	Email verification, password reset, magic links

This guide covers MakerKit email configuration. For Supabase Auth emails, see the Authentication Emails guide.

Choosing a Mailer Provider

MakerKit supports two mailer implementations:

Nodemailer (Default)

Best for: Most production deployments using any SMTP provider (SendGrid, Mailgun, Amazon SES, etc.)

Works with any SMTP server
Requires Node.js runtime (not compatible with Edge)
Full control over SMTP configuration

Resend

Best for: Edge runtime deployments, simpler setup, or if you're already using Resend

HTTP-based API (Edge compatible)
No SMTP configuration needed
Requires Resend account and API key

Configuring Nodemailer

Nodemailer is the default provider. Set these environment variables in apps/web/.env:

MAILER_PROVIDER=nodemailer
# SMTP Configuration
EMAIL_HOST=smtp.your-provider.com
EMAIL_PORT=587
EMAIL_USER=your-smtp-username
EMAIL_PASSWORD=your-smtp-password
EMAIL_TLS=true
EMAIL_SENDER=YourApp <hello@yourapp.com>

Environment Variables Explained

Variable	Description	Example
`EMAIL_HOST`	SMTP server hostname	`smtp.sendgrid.net`, `email-smtp.us-east-1.amazonaws.com`
`EMAIL_PORT`	SMTP port (587 for STARTTLS, 465 for SSL)	`587`
`EMAIL_USER`	SMTP authentication username	Varies by provider
`EMAIL_PASSWORD`	SMTP authentication password or API key	Varies by provider
`EMAIL_TLS`	Use secure connection (`true` for SSL on port 465, `false` for STARTTLS on port 587)	`true`
`EMAIL_SENDER`	Sender name and email address	`MyApp <noreply@myapp.com>`

Note: EMAIL_TLS maps to Nodemailer's secure option. When true, the connection uses SSL/TLS from the start (typically port 465). When false, the connection starts unencrypted and upgrades via STARTTLS (typically port 587). Most modern providers use port 587 with EMAIL_TLS=false.

Provider-Specific Configuration

SendGrid

EMAIL_HOST=smtp.sendgrid.net
EMAIL_PORT=587
EMAIL_USER=apikey
EMAIL_PASSWORD=SG.your-api-key-here
EMAIL_TLS=true
EMAIL_SENDER=YourApp <verified-sender@yourdomain.com>

Amazon SES

EMAIL_HOST=email-smtp.us-east-1.amazonaws.com
EMAIL_PORT=587
EMAIL_USER=your-ses-smtp-username
EMAIL_PASSWORD=your-ses-smtp-password
EMAIL_TLS=true
EMAIL_SENDER=YourApp <verified@yourdomain.com>

Mailgun

EMAIL_HOST=smtp.mailgun.org
EMAIL_PORT=587
EMAIL_USER=postmaster@your-domain.mailgun.org
EMAIL_PASSWORD=your-mailgun-password
EMAIL_TLS=true
EMAIL_SENDER=YourApp <noreply@your-domain.mailgun.org>

EMAIL_SENDER Format

The EMAIL_SENDER variable accepts two formats:

# With display name (recommended)
EMAIL_SENDER=YourApp <hello@yourapp.com>
# Email only
EMAIL_SENDER=hello@yourapp.com

Verify Your Sender Domain

Most email providers require you to verify your sending domain before emails will be delivered. Check your provider's documentation for domain verification instructions.

Configuring Resend

To use Resend instead of Nodemailer:

MAILER_PROVIDER=resend
RESEND_API_KEY=re_your-api-key
EMAIL_SENDER=YourApp <hello@yourapp.com>

Getting a Resend API Key

Create an account at resend.com
Add and verify your sending domain
Generate an API key from the dashboard
Add the key to your environment variables

Edge Runtime Compatible

Resend uses HTTP requests instead of SMTP, making it compatible with Vercel Edge Functions and Cloudflare Workers. If you deploy to edge runtimes, Resend is the recommended choice.

Verifying Your Configuration

After configuring your email provider, test it by triggering an email in your application:

Start your development server: pnpm dev
Sign up a new user and invite them to a team
Check that the invitation email arrives

For local development, emails are captured by Mailpit at http://localhost:54324. See the Local Development guide for details.

Common Configuration Errors

Connection Timeout

If emails fail with connection timeout errors:

Verify EMAIL_HOST and EMAIL_PORT are correct
Check if your hosting provider blocks outbound SMTP (port 25, 465, or 587)
Some providers like Vercel block raw SMTP; use Resend instead

Authentication Failed

If you see authentication errors:

Double-check EMAIL_USER and EMAIL_PASSWORD
Some providers use API keys as passwords (e.g., SendGrid uses apikey as username)
Ensure your credentials have sending permissions

Emails Not Delivered

If emails send but don't arrive:

Verify your sender domain is authenticated (SPF, DKIM, DMARC)
Check the spam folder
Review your email provider's delivery logs
Ensure EMAIL_SENDER uses a verified email address

Next Steps

Send your first email using the mailer API
Create custom email templates with React Email
Configure Supabase Auth emails for verification flows