nodemailer

Easy as cake e-mail sending from your Node.js applications

weekly downloads9.6M

versionv8.0.1

licenseMIT-0

categorybackend

Nodemailer

Overview

Nodemailer is a battle-tested email library for Node.js applications that handles everything from simple transactional emails to complex multi-part messages with attachments. With over 9.5 million weekly downloads, it's become the de facto standard for server-side email in the Node ecosystem. Unlike service-specific SDKs, Nodemailer abstracts transport protocols—you can send through SMTP servers, Amazon SES, Sendmail, or even direct MX lookups—without rewriting your email logic.

The library emerged to solve a fundamental problem: Node.js needed a reliable, non-blocking way to send emails that didn't depend on external binaries or native addons. Nodemailer achieves this with pure JavaScript, offering zero runtime dependencies as of version 8.x while maintaining full Unicode support, automatic text/HTML fallbacks, and robust error handling. It's designed to prevent common security pitfalls like RCE vulnerabilities and includes built-in support for TLS, OAuth2 authentication, and DKIM email signing.

Developers choose Nodemailer when they need full control over email composition and delivery without vendor lock-in. It's particularly popular in Express.js applications, serverless functions, and backend services that handle user notifications, password resets, or automated reporting. The plugin architecture allows extending functionality—from custom transport layers to message hooks—making it suitable for everything from prototype MVPs to enterprise applications processing thousands of emails daily.

Quick Start

typescript

const nodemailer = require('nodemailer');

async function sendWelcomeEmail(userEmail, userName) {
  const transporter = nodemailer.createTransport({
    host: 'smtp.gmail.com',
    port: 587,
    secure: false,
    auth: {
      user: process.env.SMTP_USER,
      pass: process.env.SMTP_APP_PASSWORD
    }
  });

  const mailOptions = {
    from: '"MyApp Team" <noreply@myapp.com>',
    to: userEmail,
    subject: `Welcome to MyApp, ${userName}!`,
    text: `Hi ${userName},\n\nThanks for signing up. Visit your dashboard to get started.`,
    html: `<h1>Hi ${userName},</h1><p>Thanks for signing up. <a href="https://myapp.com/dashboard">Visit your dashboard</a> to get started.</p>`,
    attachments: [
      {
        filename: 'logo.png',
        path: './assets/logo.png',
        cid: 'logo@myapp'
      }
    ]
  };

  try {
    const info = await transporter.sendMail(mailOptions);
    console.log('Email sent:', info.messageId);
    return { success: true, messageId: info.messageId };
  } catch (error) {
    console.error('Email error:', error);
    throw new Error(`Failed to send email: ${error.message}`);
  }
}

sendWelcomeEmail('user@example.com', 'Alice');

Use Cases

Transactional emails in web applications: Send password reset links, email verification tokens, or order confirmations from Express/Fastify APIs. Nodemailer integrates cleanly with request handlers and supports async/await patterns for modern routing.

Automated reporting systems: Generate daily analytics reports or system health alerts and email them to stakeholders with attached CSV/PDF files. The stream-based attachment handling prevents memory issues with large files.

Multi-tenant SaaS platforms: Different customers use different SMTP credentials or services (SendGrid for one tenant, Mailgun for another). Nodemailer's transporter pattern lets you instantiate multiple configurations and select at runtime.

Email testing in CI/CD pipelines: Use Ethereal.email integration (built into Nodemailer) to capture test emails during automated testing without hitting real inboxes or requiring mock servers.

Self-hosted newsletter systems: Build custom email campaigns that send HTML templates with personalized content and track bounces through SMTP reply monitoring, avoiding third-party service costs for smaller lists.

Pros & Cons

Pros

+Zero runtime dependencies reduce attack surface and bundle size—no transitive dependency vulnerabilities to monitor
+Transport-agnostic design means switching from SMTP to SES or another provider requires changing only configuration, not application code
+Comprehensive MIME support including inline images, multiple attachments, custom headers, and calendar invites without manual RFC compliance
+Built-in security features like DKIM signing, OAuth2, and TLS prevent common email authentication issues
+Plugin ecosystem and event hooks enable advanced scenarios like rate limiting, retry logic, or custom authentication flows

Cons

−SMTP configuration can be complex for beginners—understanding port 587 vs 465, STARTTLS, and authentication methods requires protocol knowledge
−No built-in template engine means you need to integrate Handlebars, Pug, or similar libraries separately for dynamic HTML emails
−Rate limiting and queue management must be implemented manually—high-volume sending requires external job queues like Bull or custom retry logic
−Error messages from SMTP servers are often cryptic and require debugging skills to interpret delivery failures or authentication rejections
−Testing email delivery locally requires either a real SMTP server, third-party services like Ethereal, or mock transport setup

Install

bash

npm install nodemailer

bash

pnpm add nodemailer

bash

bun add nodemailer

Overview

Quick Start

typescript

const nodemailer = require('nodemailer');

async function sendWelcomeEmail(userEmail, userName) {
  const transporter = nodemailer.createTransport({
    host: 'smtp.gmail.com',
    port: 587,
    secure: false,
    auth: {
      user: process.env.SMTP_USER,
      pass: process.env.SMTP_APP_PASSWORD
    }
  });

  const mailOptions = {
    from: '"MyApp Team" <noreply@myapp.com>',
    to: userEmail,
    subject: `Welcome to MyApp, ${userName}!`,
    text: `Hi ${userName},\n\nThanks for signing up. Visit your dashboard to get started.`,
    html: `<h1>Hi ${userName},</h1><p>Thanks for signing up. <a href="https://myapp.com/dashboard">Visit your dashboard</a> to get started.</p>`,
    attachments: [
      {
        filename: 'logo.png',
        path: './assets/logo.png',
        cid: 'logo@myapp'
      }
    ]
  };

  try {
    const info = await transporter.sendMail(mailOptions);
    console.log('Email sent:', info.messageId);
    return { success: true, messageId: info.messageId };
  } catch (error) {
    console.error('Email error:', error);
    throw new Error(`Failed to send email: ${error.message}`);
  }
}

sendWelcomeEmail('user@example.com', 'Alice');

Use Cases

Email testing in CI/CD pipelines: Use Ethereal.email integration (built into Nodemailer) to capture test emails during automated testing without hitting real inboxes or requiring mock servers.

Pros & Cons

Pros

+Zero runtime dependencies reduce attack surface and bundle size—no transitive dependency vulnerabilities to monitor
+Transport-agnostic design means switching from SMTP to SES or another provider requires changing only configuration, not application code
+Comprehensive MIME support including inline images, multiple attachments, custom headers, and calendar invites without manual RFC compliance
+Built-in security features like DKIM signing, OAuth2, and TLS prevent common email authentication issues
+Plugin ecosystem and event hooks enable advanced scenarios like rate limiting, retry logic, or custom authentication flows

Cons

−SMTP configuration can be complex for beginners—understanding port 587 vs 465, STARTTLS, and authentication methods requires protocol knowledge
−No built-in template engine means you need to integrate Handlebars, Pug, or similar libraries separately for dynamic HTML emails
−Rate limiting and queue management must be implemented manually—high-volume sending requires external job queues like Bull or custom retry logic
−Error messages from SMTP servers are often cryptic and require debugging skills to interpret delivery failures or authentication rejections
−Testing email delivery locally requires either a real SMTP server, third-party services like Ethereal, or mock transport setup