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.

完整安装指南与集成提示词将在购买后解锁。

PHP, Laravel & Business Scripts

免费