Nodemailer

Nodemailer is the de facto standard library for sending email from Node.js applications, downloaded millions of times a week with zero runtime dependencies. It ships pluggable transports for direct SMTP delivery, connection pooling, Amazon SES, sendmail, and test-friendly JSON/stream output, all wrapped behind one consistent createTransport() API.

Beyond raw delivery, Nodemailer handles the parts developers usually get wrong by hand: MIME multipart composition with attachments and embedded images, DKIM signing, RFC 5322 address parsing, and OAuth2 authentication for Gmail and Outlook. The library has shipped since 2011, stayed committed to CommonJS and Node 6+ compatibility for maximum embeddability, and remains under active, security-conscious maintenance by its original author.

What You Get

• One createTransport() entry point that auto-detects and dispatches to SMTP, SMTP pool, SES, sendmail, stream, or JSON transports based on the options passed in.
• A full MIME composer (lib/mail-composer, lib/mime-node) that builds multipart messages with attachments, inline images, and calculated Content-Type boundaries without extra dependencies.
• Built-in DKIM signing (lib/dkim) so outgoing mail can be cryptographically signed without a separate library.
• An RFC 5322-compliant address parser (lib/addressparser) that turns free-form ‘Name <email>’ strings and comma-separated lists into structured recipient objects.
• OAuth2 token handling (lib/xoauth2) for authenticating against Gmail and Outlook/Office 365 without storing a static password.

Common Use Cases

• Transactional email from a Node.js backend — password resets, order confirmations, signup verification — sent over SMTP or Amazon SES.
• Local development and CI, using the streamTransport or jsonTransport options to capture composed messages without touching a live mail server.
• High-volume sending through SMTPPool, which keeps persistent connections open and rate-limits outbound messages against a provider’s throughput cap.
• OAuth2-authenticated sending through Gmail or Microsoft 365 accounts, avoiding app passwords or storing raw account credentials.

Under The Hood

Architecture

Nodemailer’s entry point, lib/nodemailer.js, exposes a single createTransport(transporter, defaults) function that inspects the passed options (or a smtp://…/direct: connection URL parsed via lib/shared) and dispatches to one of six bundled transport constructors — SMTPTransport, SMTPPool, SESTransport, SendmailTransport, StreamTransport, or JSONTransport — before wrapping the result in a Mail instance from lib/mailer/index.js. Mail (an EventEmitter subclass) is the layer every message actually flows through: it normalizes the caller’s message object, invokes the DKIM signer (lib/dkim) when configured, and calls MailComposer (lib/mail-composer) to walk the recipient/attachment data into a MIME tree via lib/mime-node before handing the resulting stream to the transport’s own send(mail, callback) method — a duck-typed contract requiring only name, version, and send(). The one genuinely hot, security-sensitive path is lib/smtp-connection/index.js (2000+ lines), a hand-rolled SMTP/LMTP/ESMTP client that owns socket lifecycle, STARTTLS negotiation, and line-buffered response parsing, including a documented binary-container trick (decodeServerResponse) to reassemble multi-byte UTF-8 server replies split across TCP chunks. Supporting concerns — address parsing (lib/addressparser), OAuth2 token generation (lib/xoauth2), punycode domain handling, and MIME/base64/quoted-printable encoding — are each isolated into their own single-purpose lib/ subdirectory.

Tech Stack

The package declares zero runtime dependencies in package.json — every SMTP, MIME, DKIM, and OAuth2 concern is implemented in-house rather than delegated to third-party packages, a deliberate constraint stated in the project’s own CLAUDE.md. It targets Node.js >=6.0.0 and is written as strict CommonJS in ES2017 script mode: no ESM import, no optional chaining, no class fields, enforced by an ESLint config pinned to ecmaVersion 2017 and sourceType ‘script’, plus a dedicated test:syntax script that runs the suite inside a node:6-alpine Docker container to catch accidental modern syntax. Formatting is Prettier-managed, linting is ESLint 10 with eslint-config-prettier to avoid rule overlap, and releases are fully automated by the release-please GitHub Action, which derives version bumps and CHANGELOG.md entries from Conventional Commit messages on master rather than manual tagging.

Code Quality

Testing is substantial: 39 dedicated *-test.js files under test/, mirroring the lib/ directory 1:1, run via Node’s native node —test runner (~480+ assertions, ~150s, serial execution) with c8 for coverage. Most SMTP-facing suites (test/smtp-connection, test/smtp-transport, test/smtp-pool) spin up real smtp-server instances on ephemeral ports rather than mocking the protocol, and some drop to raw net servers when a test needs byte-exact control over server replies, such as injecting invalid UTF-8 to exercise decodeServerResponse’s fallback path. The project’s own contribution guidance is explicit that security-sensitive code — lib/smtp-connection, address parsing, header generation, DKIM — requires tests exercising the failure mode, not just the happy path, reflecting real awareness of SMTP command-injection risk from user-controllable envelope/header values. Naming is consistent camelCase/PascalCase throughout, ‘use strict’ is present at the top of every file, and inline JSDoc comments document option objects on public constructors.

API Design The public surface is intentionally small: one createTransport() factory that accepts either an options object or a smtp://…/direct: connection string, returning a Mail instance whose only method callers typically touch is sendMail(). The library still exposes a callback-first API throughout (transporter.sendMail(options, callback)), with promise support layered on top only when no callback is supplied — a deliberate legacy-compatible design choice rather than an oversight, and one the project explicitly asks contributors not to convert wholesale. Getting started requires no more than an options object and one sendMail() call, and swapping the underlying transport (SMTP to SES to a test JSON transport) is a one-line change to the constructor input with no change to calling code. The tradeoff for this stability is limited native TypeScript support — types are maintained separately as @types/nodemailer rather than shipped in-tree — and callback-based internals that read as dated next to newer promise/async-first libraries.