Required dependencies

npm install nodemailer

The source is zero-dependency at runtime; all require() calls inside source/ resolve to Node.js built-ins (stream, crypto, fs, net, tls, http, https, url, zlib, path, dns). No native modules, no pod install, no Android linking, no npx expo prebuild.

If you drop the raw source into a TypeScript project and want types:

npm install --save-dev @types/nodemailer

Project setup

1. Copy the source/ directory into your project, e.g. src/vendor/nodemailer/.
2. The entry point is source/nodemailer.js. Create an alias so imports are clean:

// tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "nodemailer": ["src/vendor/nodemailer/nodemailer.js"]
    }
  }
}

3. If you use Webpack or similar bundlers, add a resolve alias:

// webpack.config.js
resolve: {
  alias: {
    nodemailer: path.resolve(__dirname, 'src/vendor/nodemailer/nodemailer.js')
  }
}

4. Provide SMTP credentials via environment variables (never hardcode):

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=user@example.com
SMTP_PASS=secret

5. No build step is required; the source is plain CommonJS. TypeScript consumers can require() or use dynamic import() with esModuleInterop: true.

Public API

encode (base64)

import { encode, wrap } from './source/base64/index.js';

function encode(buffer: Buffer | string): string;
function wrap(str: string, lineLength?: number): string;

encode converts a Buffer or UTF-8 string to a base64 string. wrap inserts \r\n soft line-breaks every lineLength characters (default 76), required for MIME compliance. Use these when manually constructing MIME attachment payloads.

JSONTransport

import JSONTransport from './source/json-transport/index.js';

class JSONTransport {
  name: string;           // 'JSONTransport'
  version: string;
  send(mail: MailMessage, done: (err: Error | null, info?: any) => void): void;
}

Pass an instance to createTransport when you want to capture what would have been sent as a plain JavaScript object instead of delivering it. Useful in test environments and CI pipelines where real delivery must be suppressed.

nmfetch (fetch)

import nmfetch from './source/fetch/index.js';
import { Cookies } from './source/fetch/index.js';

function nmfetch(url: string, options?: FetchOptions): PassThrough;

A lightweight HTTP/HTTPS fetch returning a PassThrough stream. Used internally by XOAuth2 and SES transport but available standalone. It handles gzip/deflate decompression, Basic auth from URL, redirect following (up to 5 by default), and cookie management via the exported Cookies class.

Working examples

Scenario - Send a plain-text email over SMTP

Basic single-connection SMTP delivery using the source directly.

const nodemailer = require('./source/nodemailer');

const transport = nodemailer.createTransport({
    host: process.env.SMTP_HOST,
    port: Number(process.env.SMTP_PORT) || 587,
    secure: false,
    auth: {
        user: process.env.SMTP_USER,
        pass: process.env.SMTP_PASS
    },
    tls: {
        rejectUnauthorized: true,
        minVersion: 'TLSv1.2'
    }
});

async function sendWelcome(to: string): Promise<void> {
    const info = await transport.sendMail({
        from: '"My App" <no-reply@example.com>',
        to,
        subject: 'Welcome',
        text: 'Hello, welcome to our service.',
        html: '<p>Hello, welcome to our service.</p>'
    });
    console.log('Message ID:', info.messageId);
}

sendWelcome('alice@example.com');

Scenario - Capture output as JSON in tests

Use JSONTransport to prevent real delivery during unit tests while still asserting on message structure.

const JSONTransport = require('./source/json-transport/index');
const nodemailer = require('./source/nodemailer');

const transport = nodemailer.createTransport(new JSONTransport({ logger: false }));

async function testEmail() {
    const info = await transport.sendMail({
        from: 'test@example.com',
        to: 'dest@example.com',
        subject: 'Test subject',
        text: 'Body text'
    });
    // info.message is the raw JSON representation
    console.log(JSON.stringify(info.message, null, 2));
}

testEmail();

Scenario - Encode a file attachment manually with base64 utilities

When building a custom MIME pipeline, use encode and wrap directly.

import * as fs from 'fs';
const { encode, wrap } = require('./source/base64/index');

function encodeAttachment(filePath: string): string {
    const buffer = fs.readFileSync(filePath);
    const b64 = encode(buffer);
    return wrap(b64, 76); // MIME-compliant 76-char line wrapping
}

const encodedPdf = encodeAttachment('./report.pdf');
console.log('First line:', encodedPdf.split('\r\n')[0]);

Scenario - Use pooled SMTP transport for bulk sending

Pool connections to avoid repeated handshake overhead when sending many messages.

const nodemailer = require('./source/nodemailer');

const pool = nodemailer.createTransport({
    pool: true,
    maxConnections: 5,
    maxMessages: 100,
    host: process.env.SMTP_HOST,
    port: 465,
    secure: true,
    auth: {
        user: process.env.SMTP_USER,
        pass: process.env.SMTP_PASS
    }
});

const recipients = ['a@example.com', 'b@example.com', 'c@example.com'];

Promise.all(
    recipients.map(to =>
        pool.sendMail({ from: 'bulk@example.com', to, subject: 'Announcement', text: 'Hi!' })
    )
).then(() => {
    pool.close();
    console.log('All sent');
});

File walkthrough

• nodemailer.js - Entry point; exports createTransport, createTestAccount, createTransporter, and getTestMessageUrl.
• errors.js - Defines typed error classes (SMTPError) used throughout the library.
• mailer/index.js - Mailer class that wraps a transport and exposes sendMail.
• mailer/mail-message.js - MailMessage wraps raw mail data and provides normalize().
• smtp-transport/index.js - Single-connection SMTP transport; delegates to smtp-connection.
• smtp-pool/index.js - Pool manager; holds multiple pool-resource instances.
• smtp-pool/pool-resource.js - Wraps one SMTPConnection as a reusable pool slot.
• smtp-connection/index.js - Core SMTP protocol implementation (EHLO, AUTH, STARTTLS, DATA).
• smtp-connection/data-stream.js - Transforms message bytes into dot-stuffed SMTP DATA format.
• smtp-connection/http-proxy-client.js - Opens a TCP tunnel through an HTTP CONNECT proxy.
• dkim/index.js - Orchestrates DKIM signing; buffers or caches large messages to disk.
• dkim/message-parser.js - Splits an RFC 822 stream into headers and body.
• dkim/relaxed-body.js - Implements the DKIM "relaxed" body canonicalization transform.
• dkim/sign.js - Generates the DKIM-Signature header value.
• mail-composer/index.js - Builds a complete MIME message tree from a mail data object.
• mime-node/index.js - Recursive MIME node with encoding, boundary, and header logic.
• mime-node/last-newline.js - Transform that ensures a trailing newline before end.
• mime-node/le-unix.js / le-windows.js - Line-ending normalization transforms.
• mime-funcs/index.js - Header encoding, content-type parsing, filename encoding helpers.
• mime-funcs/mime-types.js - Static map of extension → MIME type.
• addressparser/index.js - Tokenizes and parses RFC 5322 address strings.
• base64/index.js - encode, wrap, and Encoder Transform stream.
• qp/index.js - Quoted-Printable encode/decode and Encoder/Decoder Transform streams.
• shared/index.js - Logger factory (getLogger), resolveHostname, proxy URL parser.
• fetch/index.js - Internal HTTP fetch with redirect, auth, decompression, cookie support.
• fetch/cookies.js - Simple cookie jar used by fetch.
• punycode/index.js - Converts Unicode domain labels to ASCII-compatible encoding (ACE).
• xoauth2/index.js - Manages XOAuth2 access tokens, handles refresh automatically.
• well-known/index.js - Looks up transport options for named services.
• well-known/services.json - Database of well-known SMTP service configurations.
• json-transport/index.js - Transport that emits message as a JSON object, no delivery.
• sendmail-transport/index.js - Spawns the system sendmail binary with the message on stdin.
• ses-transport/index.js - Calls the AWS SES SendRawEmail API.
• stream-transport/index.js - Pipes the composed message into a supplied writable stream.

Common pitfalls and fixes

• secure: true on port 587 causes immediate TLS rejection - Set secure: false for port 587 (STARTTLS); only use secure: true for port 465.
• Self-signed or expired certs fail silently in production - Set tls.rejectUnauthorized: false only during development; pin tls.minVersion: 'TLSv1.2' in production.
• DKIM signing fails with ENOENT on large messages - Set cacheDir to a writable temp path; the signer buffers messages >2 MB to disk and needs a real directory.
• XOAuth2 token refresh loops when expires_in is missing from provider response - Explicitly set options.expires (Unix ms) when constructing the XOAuth2 instance.
• CJS/ESM interop: require() of ES module fails - The source is CommonJS; use require() or configure esModuleInterop: true + allowSyntheticDefaultImports: true in tsconfig.json.
• Pool never closes after bulk send - Always call transport.close() on a pooled transport; open connections keep the Node.js process alive indefinitely.

Vibe-coding prompt template

I have dropped the Nodemailer library source (nodemailer@8.0.5) into my project
at `src/vendor/nodemailer/`. The entry point is `src/vendor/nodemailer/nodemailer.js`.
A full description of every module is in `USAGE.md` next to this source directory.

Please help me integrate Nodemailer into my existing Node.js/TypeScript project
step-by-step:

1. Add a tsconfig path alias so I can import from 'nodemailer' pointing at
   `src/vendor/nodemailer/nodemailer.js`.
2. Create a `src/lib/mailer.ts` module that:
   - Reads SMTP config from environment variables (SMTP_HOST, SMTP_PORT,
     SMTP_USER, SMTP_PASS).
   - Exports a singleton `transport` created with `createTransport`.
   - Exports a typed `sendMail(options)` function.
3. Add a JSONTransport-backed transport for the test environment so no real
   emails are sent during `npm test`.
4. Show me how to enable DKIM signing by passing a `dkim` option to
   `createTransport`, referencing the real `dkim/` module inside the source.
5. Add error handling so SMTP errors (typed as `SMTPError` from
   `src/vendor/nodemailer/errors.js`) are caught and logged with a structured
   logger.

Use only the real exports documented in USAGE.md. Do not install the nodemailer
npm package; use the local source exclusively.

License and credit

Nodemailer is released under the MIT License (see source/LICENSE if present, or the license field in the upstream package.json). Upstream repository and documentation: https://nodemailer.com / https://www.npmjs.com/package/nodemailer. Original author: Andris Reinman.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

CMS, Storefront & Platform Add-ons

Free