Nuxt Server Resend

Server-side email integration for Nuxt using Resend. Send transactional emails from your Nuxt application with a simple, type-safe API.

Features

• 🔒 Server-only: All email operations happen server-side for security
• 🔑 Environment-based configuration: API key managed through runtime config
• 🎯 Type-safe: Full TypeScript support with auto-completion
• 🚀 Simple API: Easy-to-use useResend() composable in server routes
• ✅ Tested: Comprehensive test coverage included

Quick Setup

1. Install the module:

npm install @bitwo.io/resend

2. Add the module to your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['@bitwo.io/resend'],
  
  resend: {
    apiKey: process.env.NUXT_RESEND_API_KEY, // optional, can also use env variable
  },
})

3. Set your Resend API key in .env:

NUXT_RESEND_API_KEY=re_your_api_key_here

That's it! You can now send emails from your Nuxt server routes ✨

Usage

Basic Email

Create a server route to send emails:

// server/api/send-email.post.ts
export default defineEventHandler(async (event) => {
  const resend = useResend()
  
  const { data, error } = await resend.emails.send({
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Hello from Nuxt!',
    html: '<strong>Welcome to our application!</strong>',
  })
  
  if (error) {
    throw createError({
      statusCode: 500,
      message: error.message,
    })
  }
  
  return { success: true, id: data.id }
})

With Request Body

Send dynamic emails based on client requests:

// server/api/contact.post.ts
export default defineEventHandler(async (event) => {
  const body = await readBody(event)
  const resend = useResend()
  
  const { data, error } = await resend.emails.send({
    from: '[email protected]',
    to: '[email protected]',
    subject: `New contact form submission from ${body.name}`,
    html: `
      <h2>New Contact Form Submission</h2>
      <p><strong>Name:</strong> ${body.name}</p>
      <p><strong>Email:</strong> ${body.email}</p>
      <p><strong>Message:</strong> ${body.message}</p>
    `,
  })
  
  if (error) {
    throw createError({
      statusCode: 500,
      message: 'Failed to send email',
    })
  }
  
  return { success: true }
})

Using React Email Templates

Resend supports React Email templates for beautiful, maintainable emails:

// server/api/welcome-email.post.ts
import { WelcomeEmail } from '~/emails/welcome'

export default defineEventHandler(async (event) => {
  const { email, name } = await readBody(event)
  const resend = useResend()
  
  const { data, error } = await resend.emails.send({
    from: '[email protected]',
    to: email,
    subject: 'Welcome to Our Platform!',
    react: WelcomeEmail({ name }),
  })
  
  if (error) {
    throw createError({
      statusCode: 500,
      message: error.message,
    })
  }
  
  return { success: true, id: data.id }
})

With Attachments

Send emails with file attachments:

// server/api/send-invoice.post.ts
export default defineEventHandler(async (event) => {
  const resend = useResend()
  
  const { data, error } = await resend.emails.send({
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Your Invoice',
    html: '<p>Please find your invoice attached.</p>',
    attachments: [
      {
        filename: 'invoice.pdf',
        content: Buffer.from('...'), // your PDF buffer
      },
    ],
  })
  
  if (error) {
    throw createError({
      statusCode: 500,
      message: error.message,
    })
  }
  
  return { success: true }
})

Multiple Recipients

Send to multiple recipients with CC and BCC:

// server/api/send-announcement.post.ts
export default defineEventHandler(async (event) => {
  const resend = useResend()
  
  const { data, error } = await resend.emails.send({
    from: '[email protected]',
    to: ['[email protected]', '[email protected]'],
    cc: ['[email protected]'],
    bcc: ['[email protected]'],
    subject: 'Important Announcement',
    html: '<h1>Important Update</h1><p>Your message here...</p>',
  })
  
  if (error) {
    throw createError({
      statusCode: 500,
      message: error.message,
    })
  }
  
  return { success: true }
})

Reply-To Header

Specify a reply-to address:

export default defineEventHandler(async (event) => {
  const resend = useResend()
  
  const { data, error } = await resend.emails.send({
    from: '[email protected]',
    to: '[email protected]',
    replyTo: '[email protected]',
    subject: 'Customer Support',
    html: '<p>We received your request...</p>',
  })
  
  return { success: true }
})

Configuration

Module Options

Configure the module in your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['@bitwo.io/resend'],
  
  resend: {
    // Optional: Set API key directly (not recommended for production)
    apiKey: 're_your_api_key',
  },
})

Environment Variables

The recommended way to configure your API key:

# .env
NUXT_RESEND_API_KEY=re_your_api_key_here

The module will automatically use this environment variable.

Priority Order

The API key is resolved in the following order:

1. Runtime config (NUXT_RESEND_API_KEY env variable)
2. Module options (resend.apiKey in nuxt.config.ts)
3. Environment variable (NUXT_RESEND_API_KEY)

API Reference

useResend()

Server-side composable that returns a configured Resend client instance.

Returns: Resend - Resend client instance

Example:

const resend = useResend()

Throws: Error if NUXT_RESEND_API_KEY is not configured

Email Options

The resend.emails.send() method accepts the following options:

| Option | Type | Required | Description | |--------|------|----------|-------------| | from | string | ✅ | Sender email address | | to | string \| string[] | ✅ | Recipient email address(es) | | subject | string | ✅ | Email subject | | html | string | ⚠️ | HTML email content (required if react not provided) | | text | string | ❌ | Plain text email content | | react | ReactNode | ⚠️ | React Email component (required if html not provided) | | cc | string \| string[] | ❌ | CC recipients | | bcc | string \| string[] | ❌ | BCC recipients | | replyTo | string \| string[] | ❌ | Reply-to address(es) | | attachments | Attachment[] | ❌ | File attachments | | tags | Tag[] | ❌ | Email tags for organization | | headers | Record<string, string> | ❌ | Custom email headers |

For complete API documentation, visit Resend's official documentation.

Getting Your API Key

1. Sign up for a Resend account
2. Navigate to the API Keys section
3. Create a new API key
4. Add the key to your .env file

Development

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run tests
npm run test
npm run test:watch

# Run type checking
npm run test:types

License

MIT License