Skip to content
NuxtBase logo NuxtBase Docs

Email Setup

NuxtBase sends email in more places than many buyers expect.

From the current template source, email is involved in:

  • email verification
  • password reset
  • magic links
  • email OTP
  • organization invitations
  • subscription-change notifications
  • credits alerts

That is why the email driver should be configured deliberately instead of being treated as an afterthought.

The Three Supported Drivers

Section titled “The Three Supported Drivers”

NuxtBase supports three email modes through NUXT_MAIL_DRIVER:

DriverBest use caseExternal provider required
previewFast local setup and UI testingNo
smtpLocal Mailpit or your own SMTP serverYes
resendHosted delivery in staging or productionYes

Option 1: Preview Driver

Section titled “Option 1: Preview Driver”

This is the default in .env.example:

Terminal window
NUXT_MAIL_DRIVER=preview

With preview, the app renders email HTML and writes it to:

.tmp/email-previews/

This is the easiest way to verify auth flows without configuring SMTP or Resend.

Option 2: SMTP

Section titled “Option 2: SMTP”

SMTP is the right choice if you want to test delivery locally with Mailpit or use your own mail server.

Minimal SMTP setup:

Terminal window
NUXT_MAIL_DRIVER=smtp
NUXT_SMTP_HOST=127.0.0.1
NUXT_SMTP_PORT=1025
NUXT_SMTP_SECURE=false

If your SMTP provider requires credentials, set both:

Terminal window
NUXT_SMTP_USER=...
NUXT_SMTP_PASSWORD=...

Those two values are validated as a pair.

Mailpit for Local Testing

Section titled “Mailpit for Local Testing”

Mailpit is the easiest local SMTP target.

Official Mailpit docs:

On macOS, the easiest setup is Homebrew:

Terminal window
brew install mailpit
mailpit

If you want Mailpit to run automatically in the background, the official docs also show:

Terminal window
brew services start mailpit

Docker is a good alternative if you do not want a local Homebrew install:

Terminal window
docker run -d --name mailpit -p 8025:8025 -p 1025:1025 axllent/mailpit

Then open:

http://127.0.0.1:8025

to inspect delivered messages.

Option 3: Resend

Section titled “Option 3: Resend”

Resend is the simplest hosted email option in the current template.

Official Resend docs:

Recommended setup order:

  1. Add your sending domain to Resend
  2. Verify the DNS records for that domain
  3. Create an API key
  4. Update .env
  5. Test sending with the verified domain

Step 1: Add and Verify Your Domain

Section titled “Step 1: Add and Verify Your Domain”

In Resend, go to the Domains page and add a domain you control.

Resend recommends using a subdomain such as:

updates.example.com

instead of your root domain, because it isolates sending reputation more cleanly.

To verify the domain, Resend requires DNS records for:

  • SPF
  • DKIM

After those records are added, wait until the domain status becomes verified.

Step 2: Create an API Key

Section titled “Step 2: Create an API Key”

After the domain is verified, create a Resend API key in the dashboard.

Then store it in .env:

Terminal window
NUXT_RESEND_API_KEY=re_...

Resend only shows the key once when you create it, so save it immediately and keep it in environment variables rather than source code.

Step 3: Configure the Sender Address

Section titled “Step 3: Configure the Sender Address”

Configure:

Terminal window
NUXT_MAIL_DRIVER=resend
NUXT_RESEND_API_KEY=re_...
NUXT_RESEND_FROM_EMAIL=Your App <onboarding@resend.dev>

onboarding@resend.dev is Resend’s default testing sender. It is useful for basic first-run testing, but it has an important limitation:

  • you can only send testing emails to your own email address with the resend.dev sender

If you want to send to other recipients, switch the from address to your verified domain, for example:

Terminal window
NUXT_RESEND_FROM_EMAIL=NuxtBase <onboarding@updates.example.com>

If the from domain does not match a verified Resend domain, Resend can reject the request with a 403 error.

For real staging or production use, always replace onboarding@resend.dev with a sender address on your verified domain.

Debug Individual Email Templates

Section titled “Debug Individual Email Templates”

The template includes an email debug script so you can render or send a specific template without walking through the full product flow.

Terminal window
pnpm email:debug -- --template verify-email
pnpm email:debug -- --template verify-email --send --to you@example.com

Useful template names include:

  • verify-email
  • reset-password
  • organization-invitation
  • subscription-change
  • credits-alert
  • magic-link
Section titled “Recommended Email Setup Path”

Use this progression unless you already have production email ready:

  1. start with preview
  2. move to Mailpit with smtp for delivery-like local testing
  3. move to Resend or your real SMTP provider for staging and production