Installation & Configuration

Learn how to install and configure the Nuxt Email Layer in your project with different email providers.

Installation

Install the email layer as a dependency in your Nuxt project:

npm
pnpm
yarn
npm install nuxt-email-layer

Basic Setup

Add the email layer to your Nuxt configuration:

nuxt.config.ts
export default defineNuxtConfig({
  extends: ['nuxt-email-layer'],
  // Your other config...
})

That's it! The layer will work out of the box with the default MailCatcher provider for development.

Runtime Configuration

Configure email providers and settings using Nuxt's runtime configuration:

nuxt.config.ts
export default defineNuxtConfig({
  extends: ['nuxt-email-layer'],

  runtimeConfig: {
    email: {
      provider: 'mailcatcher', // or 'mailgun'
      defaultFrom: 'hello@yourapp.com',

      // MailCatcher settings (development)
      mailcatcher: {
        storageKey: 'mailcatcher'
      },

      // Mailgun settings (production)
      mailgun: {
        apiKey: process.env.MAILGUN_API_KEY,
        domain: process.env.MAILGUN_DOMAIN
      }
    }
  }
})

Environment Variables

For production usage with Mailgun, set these environment variables:

.env
# Mailgun Configuration
NUXT_EMAIL_PROVIDER=mailgun
NUXT_EMAIL_DEFAULT_FROM=noreply@yourdomain.com
NUXT_EMAIL_MAILGUN_API_KEY=key-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
NUXT_EMAIL_MAILGUN_DOMAIN=mg.yourdomain.com

Provider Configuration

MailCatcher (Development)

MailCatcher is perfect for development and testing. It catches emails instead of sending them, allowing you to review them in the devtools.

nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    email: {
      provider: 'mailcatcher',
      defaultFrom: 'hello@localhost.dev',
      mailcatcher: {
        storageKey: 'mailcatcher' // Storage key for caught emails
      }
    }
  }
})

Features:

  • 📧 Catches all emails without sending them
  • 🔍 Review emails in the devtools interface
  • 💾 Stores emails in filesystem storage
  • 🚀 Zero external dependencies

Mailgun (Production)

Mailgun is a reliable email service for production applications:

nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    email: {
      provider: 'mailgun',
      defaultFrom: 'noreply@yourdomain.com',
      mailgun: {
        apiKey: process.env.MAILGUN_API_KEY,
        domain: process.env.MAILGUN_DOMAIN
      }
    }
  }
})

Requirements:

  • Mailgun account and API key
  • Verified domain
  • API key with sending permissions

Development Tools

The email layer includes development tools that are automatically enabled in development mode:

nuxt.config.ts
export default defineNuxtConfig({
  extends: ['nuxt-email-layer'],

  // Optional: Configure devtools
  emailDevtools: {
    devtools: true // Enabled by default
  }
})

Accessing the Email Devtools

When running in development mode, visit:

http://localhost:3000/__email-devtools

Or use the Emails tab in the Nuxt Devtools.

The devtools provide:

  • 📧 Email inbox for reviewing caught emails
  • 🧪 Test email sending functionality
  • 🔍 Email content preview
  • 🗑️ Clear email history

Configuration Options

Core Settings

OptionTypeDefaultDescription
providerstring'mailcatcher'Email provider to use
defaultFromstring'hello@world.com'Default sender email address

MailCatcher Settings

OptionTypeDefaultDescription
storageKeystring'mailcatcher'Storage key for caught emails

Mailgun Settings

OptionTypeDefaultDescription
apiKeystring''Mailgun API key
domainstring''Mailgun domain

Environment-Specific Configuration

Configure different providers for different environments:

nuxt.config.ts
export default defineNuxtConfig({
  extends: ['nuxt-email-layer'],

  runtimeConfig: {
    $production:{
      email: {
        provider: 'mailgun',
        defaultFrom: 'noreply@yourdomain.com',
        mailgun: {
          apiKey: "default-api-key", //  .env NUXT_EMAIL_MAILGUN_API_KEY
          domain: "default-domain" // .env NUXT_EMAIL_MAILGUN_DOMAIN
        }
      }
    }
    $development:{
      email: {
        provider: 'mailcatcher',
        defaultFrom: 'hello@localhost.dev',
        mailcatcher: {
          storageKey: 'mailcatcher'
        }
      }
    }
  }
})

Verifying Installation

Create a test API endpoint to verify your installation:

server/api/test-email.ts
export default defineEventHandler(async (event) => {
  const email = useEmail()

  try {
    const result = await email.send({
      to: 'test@example.com',
      subject: 'Test Email',
      body: 'Hello from Nuxt Email Layer!'
    })

    return { success: true, result }
  } catch (error) {
    return { success: false, error: error.message }
  }
})

Visit /api/test-email to test your configuration. Check the devtools at /__email-devtools to see the caught email.

Next Steps

Now that you have the layer installed and configured:

Nuxt Email Layer Introduction
A complete email solution for Nuxt applications with Vue templates, multiple providers, devtools integration, and extensible hooks system.
Sending Emails
Learn how to send emails using the useEmail composable with different content types and providers.