Required dependencies

npm install nodemailer

Nodemailer has zero external runtime dependencies. All imports in the source use Node.js built-ins (stream, crypto, fs, http, https, net, zlib, url, path, dns, tls, events) plus the package's own package.json for version strings. No native add-ons, no pod install, no Android linking, no npx expo prebuild required.

If you are vendoring the source/ directory directly (without the npm package), ensure package.json exists at the project root with a version field because fetch/index.js and others read ../../package.json.

Project setup

1. Copy the source/ directory into your project, for example at src/vendor/nodemailer/.
2. If you are using TypeScript, add a path alias so imports resolve cleanly:

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

3. The source uses CommonJS (require/module.exports). If your project is ESM, either keep "type": "commonjs" for the vendor tree or use dynamic import() / a bundler interop shim.
4. Ensure a package.json at the root (or two levels above source/) contains "version". Several files do require('../../package.json').
5. Set any environment-specific variables your transport needs (SMTP credentials, AWS credentials for SES) as environment variables and read them at the call site; the library itself does not read process.env automatically.

Public API

createTransport

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

function createTransport(
  transport?: string | SMTPTransportOptions | Transport,
  defaults?: MessageOptions
): Transporter;

The primary factory. Pass an SMTP URL string, a config object, or a custom transport instance. Returns a Transporter with a .sendMail(options, callback) method. Use this for all production sending.

JSONTransport

// source/json-transport/index.js
class JSONTransport {
  name: string;           // 'JSONTransport'
  version: string;        // nodemailer package version
  send(mail: MailMessage, done: (err: Error | null, info?: object) => void): void;
}

Serialises the composed message to a JSON structure instead of sending it. Useful in test environments or CI pipelines where you want to assert on message content without an SMTP server.

base64.encode / base64.wrap / base64.Encoder

// source/base64/index.js
function encode(buffer: Buffer | string): string;
function wrap(str: string, lineLength?: number): string;
class Encoder extends Transform {
  constructor(options?: { lineLength?: number | false });
}

Low-level base64 utilities. encode converts a Buffer or string to a base64 string. wrap inserts \r\n line breaks at lineLength (default 76) for RFC compliance. Encoder is a Transform stream for large payloads. Use these directly when building custom MIME parts.

Working examples

Scenario - Send a plain-text email over SMTP

Creates a single-connection SMTP transport and sends a message with a plain-text body.

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

const transporter = nodemailer.createTransport({
  host: 'smtp.example.com',
  port: 587,
  secure: false, // STARTTLS; do NOT set true unless port 465
  auth: {
    user: process.env.SMTP_USER,
    pass: process.env.SMTP_PASS
  },
  tls: {
    minVersion: 'TLSv1.2'
  }
});

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

sendWelcome('user@example.com').catch(console.error);

Scenario - Capture outgoing email as JSON in tests

Uses JSONTransport to collect the serialised message for assertions without a real SMTP server.

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

const transporter = nodemailer.createTransport(new JSONTransport());

async function testPasswordReset() {
  const info = await transporter.sendMail({
    from: 'app@example.com',
    to: 'tester@example.com',
    subject: 'Reset your password',
    text: 'Click the link: https://example.com/reset/TOKEN'
  });
  // info.message contains the JSON-serialised message
  console.log(JSON.stringify(info.message, null, 2));
  console.assert(info.message.subject === 'Reset your password');
}

testPasswordReset();

Scenario - Encode an attachment buffer to base64 manually

Uses the base64 module directly to encode attachment content for a custom MIME builder.

const base64 = require('./source/base64');
const fs = require('fs');
const { PassThrough } = require('stream');

// One-shot encode
const pdfBuffer = fs.readFileSync('./report.pdf');
const encoded = base64.encode(pdfBuffer);
const wrapped = base64.wrap(encoded, 76);
console.log('First 80 chars:', wrapped.slice(0, 80));

// Streaming encode
const inputStream = fs.createReadStream('./report.pdf');
const encoder = new base64.Encoder({ lineLength: 76 });
const output = new PassThrough();
const chunks: Buffer[] = [];
output.on('data', (c: Buffer) => chunks.push(c));
output.on('end', () => console.log('Encoded length:', Buffer.concat(chunks).length));
inputStream.pipe(encoder).pipe(output);

File walkthrough

• nodemailer.js - Public entry point; exports createTransport, createTestAccount, getTestMessageUrl, and re-exports transport classes.
• errors.js - Defines custom Error subclasses (SMTPError, etc.) used across transports for typed error handling.
• mailer/index.js - Mailer class; wraps a transport, applies defaults, normalises message options, calls sendMail.
• mailer/mail-message.js - MailMessage wraps a raw options object and exposes normalize() for MIME compilation.
• smtp-transport/index.js - Single-connection SMTP transport; opens one connection per send call.
• smtp-pool/index.js - Pool of reusable SMTP connections; wraps pool-resource.js which manages individual slots.
• smtp-connection/index.js - Raw SMTP protocol implementation over a net/tls socket, EHLO/AUTH/DATA flow.
• smtp-connection/data-stream.js - Transparently escapes dot-stuffing in the DATA phase.
• smtp-connection/http-proxy-client.js - Opens a TCP tunnel through an HTTP CONNECT proxy before SMTP.
• mime-node/index.js - Recursive MIME tree node; streams encoded content, handles multipart boundaries.
• mime-node/last-newline.js, le-unix.js, le-windows.js - Small Transform streams for line-ending normalisation.
• mime-funcs/index.js - Charset/encoding detection, header folding, filename encoding helpers.
• mime-funcs/mime-types.js - Static MIME type extension map.
• mail-composer/index.js - High-level composer: accepts mail options, builds the MIME tree, returns a readable stream.
• dkim/index.js - Orchestrates DKIM signing; decides whether to buffer in memory or on disk.
• dkim/message-parser.js - Splits an RFC 822 stream into headers and body for canonicalisation.
• dkim/relaxed-body.js - Applies DKIM "relaxed" body canonicalisation as a Transform stream.
• dkim/sign.js - Computes the DKIM-Signature header value using crypto.
• addressparser/index.js - Tokenises and parses RFC 5322 address strings into { name, address } objects.
• base64/index.js - encode, wrap, and Encoder stream for base64 encoding.
• qp/index.js - Quoted-Printable encode, wrap, and Encoder stream.
• punycode/index.js - Encodes Unicode domain labels to ASCII-compatible encoding.
• shared/index.js - Logger factory, parseConnectionUrl, normalizeMailOptions, and other cross-cutting helpers.
• fetch/index.js - Lightweight HTTP/HTTPS client used internally (e.g., by XOAuth2 and SES transport).
• fetch/cookies.js - Cookie jar for fetch/index.js.
• xoauth2/index.js - Manages OAuth2 access-token refresh and generates the XOAUTH2 SASL string.
• ses-transport/index.js - Wraps AWS SES sendRawEmail API as a Nodemailer transport.
• sendmail-transport/index.js - Spawns the local sendmail binary and pipes the message to it.
• stream-transport/index.js - Writes the raw RFC 822 message to a provided writable stream.
• json-transport/index.js - Serialises the composed message to a JSON object; no network I/O.
• well-known/index.js - Looks up SMTP presets by service name from services.json.
• well-known/services.json - Static map of service names to host/port/secure configurations.

Common pitfalls and fixes

• secure: true on port 587 causes immediate TLS failure - secure must be false for STARTTLS (ports 25, 587); only set true for implicit TLS on port 465.
• require('../../package.json') throws when vendoring - The source resolves package.json relative to each file; place the file at src/vendor/nodemailer/ and ensure a package.json with a version field exists at the project root two levels up.
• ESM projects get require is not defined - The entire source is CJS; use createRequire or configure your bundler (esbuild, webpack) to treat the vendor tree as CommonJS.
• DKIM signing silently skipped - cacheDir must be a writable directory that already exists; the library does not create it. Also confirm privateKey is a PEM string, not a file path.
• Gmail returns 535 Authentication failed - Gmail requires an App Password (2FA enabled) or OAuth2; plain-password auth is blocked by default. Switch to XOAuth2 via xoauth2/index.js or use an App Password.
• Pool connections leak on unhandled errors - Always listen for the 'error' event on the transporter or pass a callback; unhandled promise rejections from sendMail do not automatically release pool slots in older Node versions.

Vibe-coding prompt template

I have vendored the Nodemailer library source at `src/vendor/nodemailer/` in my
Node.js / TypeScript project. I also have `USAGE.md` in the same directory which
describes every module and its exports in detail.

The upstream package is `user@example.com` (npm). The public entry point is
`src/vendor/nodemailer/nodemailer.js` which exports `createTransport`,
`createTestAccount`, and `getTestMessageUrl`.

Please help me integrate this into my project step-by-step:

1. Read `USAGE.md` to understand the available modules and their real exported
   symbols before writing any code.
2. Set up a `transporter` using `createTransport` with the SMTP credentials
   stored in `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS` environment
   variables. Use STARTTLS (secure: false, port 587).
3. Create a `sendEmail(to, subject, html, text)` helper function that calls
   `transporter.sendMail` and returns a Promise.
4. Wire this helper into my existing Express route at `POST /api/email`.
5. For the test environment (`NODE_ENV=test`), swap the SMTP transport for
   `JSONTransport` from `src/vendor/nodemailer/json-transport/index.js` so no
   real email is sent.
6. Show me any TypeScript type declarations I need to add since this is a CJS
   source without bundled `.d.ts` files.

Only use symbols documented in `USAGE.md`. Do not install additional packages.

License and credit

Nodemailer is released under the MIT License. See source/LICENSE if present, or the official repository for the full license text. Upstream package: nodemailer on npm. Original authors: Andris Reinman and contributors.

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

Hướng dẫn cài đặt đầy đủ và prompt tích hợp sẽ mở khóa sau khi mua.

PHP, Laravel & Business Scripts

Miễn phí