Skip to content
NuxtBase logo NuxtBase Docs

Email Issues

Email problems in NuxtBase usually come from one of three situations:

  • you think mail is being sent, but it is only being previewed
  • you selected a driver that is not fully configured
  • the app is using a different from-address or provider than you assumed

Problem: “Email Sent” But Nothing Arrives In An Inbox

Section titled “Problem: “Email Sent” But Nothing Arrives In An Inbox”

Check whether you are in preview mode first.

If the resolved mail driver is preview, NuxtBase writes HTML files into:

.tmp/email-previews/

and does not send a real email.

This can happen because:

  • NUXT_MAIL_DRIVER=preview
  • no mail driver is set and no Resend API key is present, so the template falls back to preview

What To Check

Section titled “What To Check”
  1. confirm the resolved driver you intended to use
  2. inspect .tmp/email-previews/ after triggering a message
  3. only debug SMTP or Resend delivery after you confirm you are not just previewing

Problem: Resend Driver Throws A Missing API Key Error

Section titled “Problem: Resend Driver Throws A Missing API Key Error”

If you explicitly choose resend, but NUXT_RESEND_API_KEY is empty, the mailer throws at send time.

Typical error:

Resend driver selected but NUXT_RESEND_API_KEY is not configured.

Fix

Section titled “Fix”

Either:

  • provide a real NUXT_RESEND_API_KEY
  • or switch the driver back to preview
  • or remove the explicit driver and let the template resolve the driver from available config

Problem: SMTP Is Configured, But Delivery Fails

Section titled “Problem: SMTP Is Configured, But Delivery Fails”

SMTP settings are only partially validated at startup.

The template checks username/password pairing, but it does not prove that the SMTP server is reachable or that the credentials are accepted.

So this can still fail at runtime even when the server boots cleanly.

What To Check

Section titled “What To Check”
  • NUXT_SMTP_HOST
  • NUXT_SMTP_PORT
  • NUXT_SMTP_SECURE
  • NUXT_SMTP_USER
  • NUXT_SMTP_PASSWORD
  • firewall or container network access to the SMTP host

Problem: The Sender Address Is Not What You Expected

Section titled “Problem: The Sender Address Is Not What You Expected”

NuxtBase resolves the from-address in this order:

  1. explicit from passed by the sender
  2. NUXT_RESEND_FROM_EMAIL
  3. siteConfig.defaultResendFrom

If your messages appear with the wrong sender, check env first before editing templates.

Problem: Verification Or Reset Emails Work Locally But Not In Production

Section titled “Problem: Verification Or Reset Emails Work Locally But Not In Production”

This is often not a template rendering problem. It is usually one of these:

  • production mail driver differs from local
  • production provider credentials are missing
  • links inside the email point to the wrong public domain

Fastest Way To Debug Email

Section titled “Fastest Way To Debug Email”
  1. confirm the active mail driver
  2. confirm whether you are previewing or sending for real
  3. confirm the API key or SMTP credentials
  4. confirm the from-address
  5. trigger one real verification or reset email and inspect the result