Email System Documentation

https://nodemailer.com
Admin
Provides comprehensive documentation for an email system, covering SMTP, DKIM, message handling,...
Tokens:54,382
Snippets:587
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Complete SMTP Connection Workflow

Source: https://nodemailer.com/extras/smtp-connection

This example shows the entire process of using SMTPConnection: establishing a connection, authenticating, sending an email, and quitting the server. Ensure you have the 'nodemailer' package installed.

```javascript
const SMTPConnection = require("nodemailer/lib/smtp-connection");  
  
const connection = new SMTPConnection({
  host: "smtp.example.com",  
  port: 587,  
  secure: false,  
  debug: true,  
  logger: true,  
});  
  
connection.on("error", (err) => {  
  // Connection failures (DNS, TCP, TLS, greeting) arrive here  
  console.error("Connection error:", err);  
});  
  
connection.connect(() => {  
  connection.login(  
    {
      user: "username",  
      pass: "password",  
    },
    (err) => {
      if (err) {
        console.error("Authentication failed:", err);
        connection.close();
        return;
      }

      const envelope = {
        from: "sender@example.com",
        to: ["recipient@example.com"],
      };

      const message = `From: sender@example.com  
To: recipient@example.com  
Subject: Test Message  
Content-Type: text/plain; charset=utf-8  
  
Hello from SMTPConnection!`;

      connection.send(envelope, message, (err, info) => {
        if (err) {
          console.error("Failed to send:", err);
        } else {
          console.log("Message sent!");
          console.log("Accepted:", info.accepted);
          console.log("Rejected:", info.rejected);
          console.log("Response:", info.response);
        }

        connection.quit();
      });
    }
  );
});  

```

--------------------------------

### Install smtp-server

Source: https://nodemailer.com/extras/smtp-server

Install the smtp-server module using npm. This is the first step before requiring it in your script.

```bash
npm install smtp-server --save  

```

--------------------------------

### Install MailParser

Source: https://nodemailer.com/extras/mailparser

Install the MailParser package using npm.

```bash
npm install mailparser  

```

--------------------------------

### Install AWS SES SDK v3

Source: https://nodemailer.com/transports/ses

Install the necessary AWS SDK package for SES v2.

```bash
npm install @aws-sdk/client-sesv2  

```

--------------------------------

### Example MAIL FROM DSN Parameters

Source: https://nodemailer.com/extras/smtp-server

Illustrates the DSN parameters that can be sent by the client during the MAIL FROM command.

```text
// Client sends: MAIL FROM:<sender@example.com> RET=FULL ENVID=abc123  
```

--------------------------------

### Example RCPT TO DSN Parameters

Source: https://nodemailer.com/extras/smtp-server

Illustrates the DSN parameters that can be sent by the client during the RCPT TO command.

```text
// Client sends: RCPT TO:<user@example.com> NOTIFY=SUCCESS,FAILURE ORCPT=rfc822;user@example.com  
```

--------------------------------

### Configure Transport with Proxy

Source: https://nodemailer.com/errors

Example of setting up a Nodemailer transporter with proxy configuration. Ensure the proxy URL is correct and the necessary modules (like 'socks' for SOCKS proxies) are installed.

```javascript
const transporter = nodemailer.createTransport({
  host: "smtp.example.com",
  port: 587,
  proxy: "http://proxy.example.com:3128",
});
```

--------------------------------

### Complete Ethereal Test Email Example

Source: https://nodemailer.com/guides/testing-with-ethereal

A full example demonstrating how to create a test account, set up a Nodemailer transporter using Ethereal's SMTP details, send a test email, and log the message ID and preview URL. This script is suitable for integration testing.

```javascript
const nodemailer = require("nodemailer");

async function sendTestEmail() {
  // Generate a test account
  const testAccount = await nodemailer.createTestAccount();

  console.log("Test account created:");
  console.log("  User: %s", testAccount.user);
  console.log("  Pass: %s", testAccount.pass);

  // Create a transporter
  const transporter = nodemailer.createTransport({
    host: testAccount.smtp.host,
    port: testAccount.smtp.port,
    secure: testAccount.smtp.secure,
    auth: {
      user: testAccount.user,
      pass: testAccount.pass,
    },
  });

  // Send a test message
  const info = await transporter.sendMail({
    from: `"Test App" <${testAccount.user}>`,
    to: "recipient@example.com",
    subject: "Hello from Ethereal!",
    text: "This message was sent using Ethereal.",
    html: "<p>This message was sent using <b>Ethereal</b>.</p>",
  });

  console.log("Message sent: %s", info.messageId);
  console.log("Preview: %s", nodemailer.getTestMessageUrl(info));
}

sendTestEmail().catch(console.error);
```

--------------------------------

### Install SOCKS Package

Source: https://nodemailer.com/smtp/proxies

Install the 'socks' package using npm. This is required to enable SOCKS proxy support in Nodemailer.

```bash
npm install socks --save  

```

--------------------------------

### Send Email with SES Transport (Callback Style)

Source: https://nodemailer.com/transports/ses

Use this example to send an email via SES using the callback style, suitable for non-async/await environments. Ensure the AWS SDK and Nodemailer are installed and configured.

```javascript
const nodemailer = require("nodemailer");
const { SESv2Client, SendEmailCommand } = require("@aws-sdk/client-sesv2");

// Create the SES client using the AWS_REGION environment variable
const sesClient = new SESv2Client({ region: process.env.AWS_REGION });

// Create the Nodemailer transport
const transporter = nodemailer.createTransport({
  SES: { sesClient, SendEmailCommand },
});

// Send the email
transporter.sendMail(
  {
    from: "sender@example.com",
    to: ["recipient@example.com"],
    subject: "Message via SES transport",
    text: "I hope this message gets sent!",
    ses: {
      // Add tags for tracking and analytics
      EmailTags: [{ Name: "tag_name", Value: "tag_value" }],
    },
  },
  (err, info) => {
    if (err) {
      console.error("Failed to send email:", err);
      return;
    }
    console.log("Email sent successfully!");
    console.log("Envelope:", info.envelope);
    console.log("Message ID:", info.messageId);
  }
);

```

--------------------------------

### Install Nodemailer

Source: https://nodemailer.com/

Install Nodemailer using npm. This is the primary method for adding the library to your Node.js project.

```bash
npm install nodemailer  

```

--------------------------------

### Complete SMTPServer DSN Example

Source: https://nodemailer.com/extras/smtp-server

A comprehensive example of an SMTPServer configured with DSN support enabled. It shows how to access DSN parameters in onMailFrom, onRcptTo, and onData handlers, and process messages with DSN context. Requires hideDSN to be false.

```javascript
const server = new SMTPServer({
  hideDSN: false, // Required to enable DSN
  onMailFrom(address, session, callback) {
    const { ret, envid } = session.envelope.dsn;
    console.log(`Mail from ${address.address}, RET=${ret}, ENVID=${envid}`);
    callback();
  },

  onRcptTo(address, session, callback) {
    // address.dsn is undefined unless the client supplied NOTIFY/ORCPT
    const { notify, orcpt } = address.dsn || {};
    console.log(`Rcpt to ${address.address}, NOTIFY=${(notify || []).join(",")}, ORCPT=${orcpt}`);
    callback();
  },

  onData(stream, session, callback) {
    // Process message with DSN context
    const { dsn } = session.envelope;
    console.log(`Processing message with DSN: ${JSON.stringify(dsn)}`);

    stream.on("end", () => {
      callback(null, "Message accepted for delivery");
    });
    stream.resume();
  },
});

```

--------------------------------

### Install AWS SES SDK v2

Source: https://nodemailer.com/transports/ses

Install the necessary AWS SDK v2 client for SES as a separate dependency. This is required for Nodemailer's SES transport.

```bash
npm install @aws-sdk/client-sesv2

```

--------------------------------

### Plugin API: mail.resolveContent Example

Source: https://nodemailer.com/plugins/create

This example demonstrates how to use `mail.resolveContent` within a plugin to resolve and log the final HTML string of an email. Ensure the callback is called with an error or no error to continue processing.

```javascript
mail.resolveContent(sourceObject, propertyName, (err, value) => {
  if (err) return done(err);
  // value is a String or Buffer depending on the input type
});

```

```javascript
function plugin(mail, done) {
  mail.resolveContent(mail.data, "html", (err, html) => {
    if (err) return done(err);
    console.log("HTML contents: %s", html.toString());
    done();
  });
}
```

--------------------------------

### Start SMTP Server Listening

Source: https://nodemailer.com/extras/smtp-server

Begin listening for incoming SMTP connections on a specified port and optionally a host. A callback can be provided for post-listen actions.

```javascript
server.listen(port[, host][, callback]);  

```

--------------------------------

### Start Local SOCKS5 Proxy with SSH

Source: https://nodemailer.com/smtp/proxies

Use SSH dynamic port forwarding to create a local SOCKS5 proxy for testing. This command forwards traffic through an SSH connection.

```bash
ssh -N -D 0.0.0.0:1080 user@remote.host  

```

--------------------------------

### Using simpleParser with Callback, Promise, and Async/Await

Source: https://nodemailer.com/extras/mailparser

Demonstrates the different ways to use the simpleParser function: callback style, Promise style, and async/await. Ensure the 'mailparser' library is installed and required.

```javascript
const { simpleParser } = require("mailparser");  
  
// Callback style  
simpleParser(source, options, (err, mail) => {  
  if (err) throw err;  
  console.log(mail.subject);  
});  
  
// Promise style  
simpleParser(source, options)  
  .then((mail) => console.log(mail.subject))  
  .catch(console.error);  
  
// async/await  
const mail = await simpleParser(source, options);
```

--------------------------------

### Complete DSN Workflow with Nodemailer

Source: https://nodemailer.com/extras/smtp-server

This example demonstrates a full DSN implementation, including parsing DSN parameters, generating RFC-compliant messages, and sending notifications using Nodemailer. It requires Nodemailer and smtp-server packages.

```javascript
const { SMTPServer } = require("smtp-server");
const nodemailer = require("nodemailer");

// Create a Nodemailer transporter for sending DSN notifications
const dsnTransporter = nodemailer.createTransport({
  host: "smtp.example.com",
  port: 587,
  secure: false,
  auth: {
    user: "dsn-sender@example.com",
    pass: "your-password",
  },
});

// DSN notification generator
class DSNNotifier {
  constructor(transporter) {
    this.transporter = transporter;
  }

  async sendSuccessNotification(envelope, messageId, deliveryTime) {
    // Only send if SUCCESS notification was requested
    const needsSuccessNotification = envelope.rcptTo.some((rcpt) => rcpt.dsn.notify && rcpt.dsn.notify.includes("SUCCESS"));

    if (!needsSuccessNotification || !envelope.mailFrom.address) {
      return;
    }

    const dsnMessage = this.generateDSNMessage({
      action: "delivered",
      status: "2.0.0",
      envelope,
      messageId,
      deliveryTime,
      diagnosticCode: "smtp; 250 2.0.0 Message accepted for delivery",
    });

    await this.transporter.sendMail({
      from: "postmaster@example.com",
      to: envelope.mailFrom.address,
      subject: "Delivery Status Notification (Success)",
      text: dsnMessage.text,
      headers: {
        "Auto-Submitted": "auto-replied",
        "Content-Type": "multipart/report; report-type=delivery-status",
      },
    });
  }

  generateDSNMessage({ action, status, envelope, messageId, deliveryTime, diagnosticCode }) {
    const { dsn } = envelope;
    const timestamp = deliveryTime || new Date().toISOString();

    // Generate RFC 3464 compliant delivery status notification
    const text = `This is an automatically generated Delivery Status Notification.  

Original Message Details:  
- Message ID: ${messageId}
- Envelope ID: ${dsn.envid || "Not provided"}
- Sender: ${envelope.mailFrom.address}
- Recipients: ${envelope.rcptTo.map((r) => r.address).join(", ")}
- Action: ${action}
- Status: ${status}
- Time: ${timestamp}

${action === "delivered" ? "Your message has been successfully delivered to all recipients." : "Delivery failed for one or more recipients."}  `;

    return { text };
  }
}

// Create DSN notifier instance
const dsnNotifier = new DSNNotifier(dsnTransporter);

// SMTP Server with DSN support
const server = new SMTPServer({
  hideDSN: false, // Required to enable DSN
  name: "mail.example.com",

  onMailFrom(address, session, callback) {
    const { dsn } = session.envelope;
    console.log(`MAIL FROM: ${address.address}, RET=${dsn.ret}, ENVID=${dsn.envid}`);
    callback();
  },

  onRcptTo(address, session, callback) {
    const { notify, orcpt } = address.dsn || {};
    console.log(`RCPT TO: ${address.address}, NOTIFY=${notify?.join(",")}, ORCPT=${orcpt}`);
    callback();
  },

  async onData(stream, session, callback) {
    const messageId = `msg-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;

    stream.on("end", async () => {
      try {
        // Simulate message delivery
        const deliveryTime = new Date();

        // Send DSN success notification if requested
        await dsnNotifier.sendSuccessNotification(session.envelope, messageId, deliveryTime);

        callback(null, `Message ${messageId} accepted for delivery`);
      } catch (error) {
        callback(error);
      }
    });

    stream.resume();
  },
});

server.listen(2525, () => {
  console.log("DSN-enabled SMTP server listening on port 2525");
});

```

--------------------------------

### Nodemailer Attachments Examples

Source: https://nodemailer.com/message/attachments

This snippet shows various ways to define attachments for an email. It includes examples for strings, buffers, file paths, streams, remote URLs, base64 content, data URIs, and raw MIME content.

```javascript
const fs = require("fs");  
  
// The attachments array goes inside your message object  
attachments: [  
  // 1. Plain text string  
  // The simplest way to create an attachment from a string  
  {
    filename: "hello.txt",
    content: "Hello world!",
  },
  
  // 2. Buffer content  
  // Useful when you have binary data in memory  
  {
    filename: "buffer.txt",
    content: Buffer.from("Hello world!", "utf8"),
  },
  
  // 3. File from the filesystem  
  // Uses streaming, which is memory-efficient for large files  
  {
    filename: "report.pdf",
    path: "/absolute/path/to/report.pdf",
  },
  
  // 4. File path only  
  // When you omit filename, Nodemailer derives it from the path  
  // The content type is also automatically detected from the file extension  
  {
    path: "/absolute/path/to/image.png",
  },
  
  // 5. Readable stream  
  // Provides full control over how content is read.  
  // This must be a Node.js stream.Readable. To use a WHATWG ReadableStream  
  // (for example the body returned by fetch()), convert it first:  
  //   const { Readable } = require("node:stream");  
  //   const response = await fetch("https://example.com/file.bin");  
  //   content: Readable.fromWeb(response.body)
  {
    filename: "notes.txt",
    content: fs.createReadStream("./notes.txt"),
  },
  
  // 6. Explicit content type  
  // Override automatic MIME type detection when needed  
  {
    filename: "data.bin",
    content: Buffer.from("deadbeef", "hex"),
    contentType: "application/octet-stream",
  },
  
  // 7. Remote URL  
  // Nodemailer fetches the content from the URL when sending  
  {
    filename: "license.txt",
    href: "https://raw.githubusercontent.com/nodemailer/nodemailer/master/LICENSE",
  },
  
  // 8. Base64-encoded string  
  // Specify the encoding when your content string is not plain text  
  {
    filename: "photo.jpg",
    content: "/9j/4AAQSkZJRgABAQAAAQABAAD...", // base64 image data (truncated)  
    encoding: "base64",
  },
  
  // 9. Data URI  
  // Useful for inline data or content from canvas elements  
  {
    path: "data:text/plain;base64,SGVsbG8gd29ybGQ=",
  },
  
  // 10. Pre-built MIME node (advanced)  
  // Provides complete control over the attachment's MIME structure  
  {
    raw: [
      "Content-Type: text/plain; charset=utf-8",
      'Content-Disposition: attachment; filename="greeting.txt"',
      "",
      "Hello world!"
    ].join("\r\n"),
  },
];  
```

--------------------------------

### Complete Example: Custom SMTP Envelope

Source: https://nodemailer.com/smtp/envelope

Demonstrates sending an email with a custom SMTP envelope using Nodemailer. This example sets a specific bounce address and recipient list, overriding default header extraction.

```javascript
const nodemailer = require("nodemailer");

async function main() {
  // Create a transport (replace with your own transport options)
  const transport = nodemailer.createTransport({
    sendmail: true,
  });

  const info = await transport.sendMail({
    from: "Mailer <mailer@example.com>", // Visible From: header
    to: "Daemon <daemon@example.com>",   // Visible To: header
    envelope: {
      from: "bounce+12345@example.com",  // Actual MAIL FROM (for bounces)
      to: [
        // Actual RCPT TO recipients (who really receive the email)
        "daemon@example.com",
        "mailer@example.com",
      ],
    },
    subject: "Custom SMTP envelope",
    text: "Hello!",
  });

  console.log("Envelope used:", info.envelope);
  // => { from: 'bounce+12345@example.com', to: [ 'daemon@example.com', 'mailer@example.com' ] }
}

main().catch(console.error);
```

--------------------------------

### Accept or Reject Connections with onConnect and onClose

Source: https://nodemailer.com/extras/smtp-server

Use onConnect to validate incoming connections before commands are processed. Use onClose for cleanup when a connection ends. Connections from localhost are rejected in this example.

```javascript
const server = new SMTPServer({
  onConnect(session, callback) {
    if (session.remoteAddress === "127.0.0.1") {
      return callback(new Error("Connections from localhost are not allowed"));
    }
    callback(); // Accept the connection
  },
  onClose(session) {
    console.log(`Connection from ${session.remoteAddress} closed`);
  },
});

```

--------------------------------

### Install SES Transport Dependencies

Source: https://nodemailer.com/transports

Install the necessary npm packages for using the Amazon SES transport with Nodemailer and the AWS SDK v3.

```bash
npm install nodemailer @aws-sdk/client-sesv2  

```

--------------------------------

### Integrate Ethereal with Test Frameworks (Jest/Mocha)

Source: https://nodemailer.com/guides/testing-with-ethereal

Set up a test account once in your test suite and reuse it for sending emails during tests. This example uses Jest's `beforeAll` hook.

```javascript
const nodemailer = require("nodemailer");

let transporter;
let testAccount;

beforeAll(async () => {
  testAccount = await nodemailer.createTestAccount();
  transporter = nodemailer.createTransport({
    host: testAccount.smtp.host,
    port: testAccount.smtp.port,
    secure: testAccount.smtp.secure,
    auth: {
      user: testAccount.user,
      pass: testAccount.pass,
    },
  });
});

test("sends welcome email", async () => {
  const info = await transporter.sendMail({
    from: "app@example.com",
    to: "newuser@example.com",
    subject: "Welcome!",
    text: "Thanks for signing up.",
  });

  expect(info.messageId).toBeDefined();
  expect(info.accepted).toContain("newuser@example.com");

  // Optionally log the preview URL for manual inspection
  console.log("Preview:", nodemailer.getTestMessageUrl(info));
});
```

--------------------------------

### Configuring Sendmail Transport

Source: https://nodemailer.com/errors

Illustrates how to configure the sendmail transport, including specifying an explicit path to the sendmail binary if needed. Verify sendmail is installed and in the system PATH.

```javascript
const transporter = nodemailer.createTransport({  
  sendmail: true,  
  path: "/usr/sbin/sendmail", // Explicit path if needed  
});  
```

--------------------------------

### SMTP Server Advertised Authentication Methods

Source: https://nodemailer.com/smtp/customauth

This example shows a typical response from an SMTP server advertising supported authentication methods, including a custom one.

```text
250-AUTH LOGIN PLAIN MY-CUSTOM-METHOD  
```

--------------------------------

### Send Email with List-* Headers

Source: https://nodemailer.com/message/list-headers

This example demonstrates how to send an email with various List-* headers using Nodemailer's 'list' option. It shows different ways to format URLs and comments for headers like List-Help, List-Unsubscribe, List-Subscribe, and List-Post.

```javascript
const nodemailer = require("nodemailer");

// 1. Create a transport (replace with your configuration)
const transporter = nodemailer.createTransport({
  host: "smtp.example.com",
  port: 587,
  auth: {
    user: "username",
    pass: "password",
  },
});

// 2. Send a message with various List-* headers
async function sendListMessage() {
  await transporter.sendMail({
    from: "sender@example.com",
    to: "recipient@example.com",
    subject: "List Message",
    text: "I hope no one unsubscribes from this list!",
    list: {
      // List-Help: <mailto:admin@example.com?subject=help>
      help: "admin@example.com?subject=help",

      // List-Unsubscribe: <http://example.com> (Comment)
      unsubscribe: {
        url: "http://example.com",
        comment: "Comment",
      },

      // Two separate List-Subscribe header lines:
      // List-Subscribe: <mailto:admin@example.com?subject=subscribe>
      // List-Subscribe: <http://example.com> (Subscribe)
      subscribe: [
        "admin@example.com?subject=subscribe",
        {
          url: "http://example.com",
          comment: "Subscribe",
        },
      ],

      // Multiple URLs in a single List-Post header line:
      // List-Post: <http://example.com/post>, <mailto:admin@example.com?subject=post> (Post)
      post: [
        [
          "http://example.com/post",
          {
            url: "admin@example.com?subject=post",
            comment: "Post",
          },
        ],
      ],
    },
  });

  console.log("List message sent");
}

sendListMessage().catch(console.error);
```

--------------------------------

### Custom HELO/EHLO Response Examples

Source: https://nodemailer.com/extras/smtp-server

Illustrates various ways to configure the HELO/EHLO response, including default behavior, custom formal greetings, simple greetings, and using both placeholders.

```javascript
// Default behavior (no configuration needed)
// "250 hostname Nice to meet you, client.example.com"

// Custom formal greeting
heloResponse: "Welcome to %s mail server"
// "250 Welcome to hostname mail server"

// Simple greeting without placeholders
heloResponse: "Hello"
// "250 Hello"

// Using both placeholders
heloResponse: "%s greets %s"
// "250 hostname greets client.example.com"

```

--------------------------------

### Configure Transport with OAuth2

Source: https://nodemailer.com/errors

Example configuration for Nodemailer using OAuth2 authentication. Ensure you provide the correct user, clientId, clientSecret, and refreshToken.

```javascript
// OAuth2 configuration example
const transporter = nodemailer.createTransport({
  service: "gmail",
  auth: {
    type: "OAuth2",
    user: "your.email@gmail.com",
    clientId: "your-client-id",
    clientSecret: "your-client-secret",
    refreshToken: "your-refresh-token",
  },
});
```

--------------------------------

### Enable Stream Transport

Source: https://nodemailer.com/transports/stream

To use Stream transport, create a transporter with `streamTransport: true` in the options object. This setup is ideal for testing or custom delivery pipelines.

```javascript
const nodemailer = require("nodemailer");

const transporter = nodemailer.createTransport({
  streamTransport: true,
  // See additional options below
});

```

--------------------------------

### Send Basic Email

Source: https://nodemailer.com/

Send a simple email with plain text and HTML content. This example demonstrates the basic usage of `transporter.sendMail` with a Promise.

```javascript
try {
  const info = await transporter.sendMail({
    from: '"Example Team" <team@example.com>', // sender address
    to: "alice@example.com, bob@example.com", // list of recipients
    subject: "Hello", // subject line
    text: "Hello world?", // plain text body
    html: "<b>Hello world?</b>", // HTML body
  });

  console.log("Message sent: %s", info.messageId);
  // Preview URL is only available when using an Ethereal test account
  console.log("Preview URL: %s", nodemailer.getTestMessageUrl(info));
} catch (err) {
  console.error("Error while sending mail:", err);
}
```

--------------------------------

### Send Email with Mixed Address Formats

Source: https://nodemailer.com/message/addresses

Use this example to send an email when recipients are specified using a mix of plain email addresses and address objects. Requires SMTP transport configuration.

```javascript
const nodemailer = require("nodemailer");

async function sendEmail() {
  // Create a transport with your SMTP server settings
  const transport = nodemailer.createTransport({
    host: "smtp.example.com",
    port: 587,
    auth: {
      user: "smtp-user",
      pass: "smtp-pass"
    }
  });

  // Send an email using mixed address formats
  await transport.sendMail({
    from: "\"Example Sender\" <sender@example.com>",
    to: [
      "recipient@example.com",                              // Plain address
      { name: "Nodemailer User", address: "user@example.com" }  // Address object
    ],
    subject: "Hello from Nodemailer",
    text: "This demonstrates the different address formats."
  });
}

sendEmail().catch(console.error);

```

--------------------------------

### Sign a Specific Message with DKIM

Source: https://nodemailer.com/dkim

Configure DKIM on individual messages instead of all messages. This example sends a single email with DKIM signing applied.

```javascript
const transporter = nodemailer.createTransport({
  host: "smtp.example.com",
  port: 465,
  secure: true,
  // No DKIM configuration here
});

const info = await transporter.sendMail({
  from: "sender@example.com",
  to: "recipient@example.com",
  subject: "Hello with DKIM",
  text: "I hope this message gets read!",
  dkim: {
    domainName: "example.com",
    keySelector: "2017",
    privateKey: fs.readFileSync("./dkim-private.pem", "utf8"),
  },
});
```

--------------------------------

### Nodemailer Attachment Examples

Source: https://nodemailer.com/extras/mailcomposer

Demonstrates various ways to define attachments in Nodemailer mail options, including string content, buffers, file paths, streams, remote URLs, and data URIs.

```javascript
const fs = require("fs");

const mailOptions = {
  // ...other fields...
  attachments: [
    // Plain text string as attachment content
    { filename: "hello.txt", content: "hello world!" },

    // Binary Buffer as attachment content
    { filename: "buffer.txt", content: Buffer.from("hello world!", "utf-8") },

    // Stream content from a file on disk
    { filename: "file.txt", path: "/path/to/file.txt" },

    // Let filename and content type be inferred from the path
    { path: "/path/to/logo.png" },

    // Use a readable stream as the content source
    { filename: "stream.txt", content: fs.createReadStream("file.txt") },

    // Explicitly set the content type
    { filename: "data.bin", content: "hello world!", contentType: "application/octet-stream" },

    // Fetch attachment content from a remote URL
    { filename: "license.txt", path: "https://raw.githubusercontent.com/nodemailer/nodemailer/master/LICENSE" },

    // Decode a base64-encoded string into attachment content
    { filename: "base64.txt", content: "aGVsbG8gd29ybGQh", encoding: "base64" },

    // Use a data URI as the content source
    { path: "data:text/plain;base64,aGVsbG8gd29ybGQ=" },
  ],
};

```

--------------------------------

### Create and Use a Pooled SMTP Transporter

Source: https://nodemailer.com/smtp/pooled

Create a single Nodemailer transporter instance with pooling enabled and reuse it for sending multiple emails. This example demonstrates setting up a pooled transporter with specific connection limits and then sending a sample email.

```javascript
const nodemailer = require("nodemailer");  
  
// Create ONE transporter instance and reuse it throughout your application.  
// The transporter manages up to `maxConnections` persistent connections internally.  
const transporter = nodemailer.createTransport({  
  host: "smtp.example.com",  
  port: 465,  
  secure: true,  
  pool: true, // Enable connection pooling  
  maxConnections: 5, // Maximum number of simultaneous connections (default: 5)  
  maxMessages: 100, // Messages per connection before reconnecting (default: 100)  
  auth: {  
    user: process.env.SMTP_USER,  
    pass: process.env.SMTP_PASS,  
  },  
});  
  
// Send emails using the shared transporter.  
// Do NOT create a new transporter for each message - that defeats the purpose of pooling.  
await transporter.sendMail({  
  from: "Newsletters <noreply@example.com>",  
  to: "alice@example.com",  
  subject: "Hello pooled world",  
  text: "Hi Alice!",  
});  

```

--------------------------------

### Verify SES Transport Configuration

Source: https://nodemailer.com/transports/ses

Use the `transporter.verify()` method to check your SES transport configuration. This method sends an invalid test message to confirm credentials and setup.

```javascript
// Verify SES configuration
const isValid = await transporter.verify();
console.log("SES configuration is valid:", isValid);

```

--------------------------------

### build(callback)

Source: https://nodemailer.com/extras/mailcomposer

Generates the complete message and returns it as a Buffer through a callback function. Use this method when you need the entire message in memory, for example to save it to a file or send it via an API. If no callback is provided, build() returns a Promise that resolves with the message Buffer.

```APIDOC
## build(callback)

### Description
Generates the complete message and returns it as a Buffer through a callback function or a Promise. Use this method when you need the entire message in memory.

### Method
`build(callback)` or `build()`

### Endpoint
N/A (Method on MailComposer instance)

### Parameters
#### Callback
- **callback** (function) - Optional - A callback function that receives an error and the message Buffer.
  - **err** (Error) - The error object if an error occurred.
  - **message** (Buffer) - The complete RFC 822 message as a Buffer.

### Request Example (Callback)
```javascript
const mail = new MailComposer({ from: "you@example.com" /* ... */ });
mail.compile().build((err, message) => {
  if (err) throw err;
  process.stdout.write(message);
});
```

### Request Example (Promise)
```javascript
const message = await mail.compile().build();
```

### Response
#### Success Response (Callback)
- **message** (Buffer) - The complete RFC 822 message as a Buffer.

#### Success Response (Promise)
- **message** (Buffer) - The complete RFC 822 message as a Buffer.
```

--------------------------------

### Specify Custom Sendmail Binary Path

Source: https://nodemailer.com/transports/sendmail

Use the `path` option to specify the exact location of the sendmail binary if it's not in your system's PATH. This example demonstrates configuring the transporter and sending a test email.

```javascript
const nodemailer = require("nodemailer");

const transporter = nodemailer.createTransport({
  sendmail: true,
  path: "/usr/sbin/sendmail",
});

transporter.sendMail(
  {
    from: "sender@example.com",
    to: "recipient@example.com",
    subject: "Test message",
    text: "I hope this message gets delivered!",
  },
  (err, info) => {
    if (err) {
      console.error(err);
      return;
    }
    console.log(info.envelope);
    console.log(info.messageId);
  }
);

```

--------------------------------

### Pass Custom Command-Line Arguments to Sendmail

Source: https://nodemailer.com/transports/sendmail

Configure the `args` option to provide custom command-line arguments to the sendmail binary. This example overrides the default arguments to set a custom bounce address using the `-f` flag.

```javascript
const transporter = nodemailer.createTransport({
  sendmail: true,
  args: ["-f", "bounce@example.com"],
});

```

--------------------------------

### Configure DKIM Signing with Multiple Keys

Source: https://nodemailer.com/dkim

Use multiple keys for rotating DKIM keys or sending mail on behalf of different subdomains. Disk caching is disabled for DKIM keys in this example.

```javascript
const transporter = nodemailer.createTransport({
  host: "smtp.example.com",
  port: 465,
  secure: true,
  dkim: {
    keys: [
      {
        domainName: "example.com",
        keySelector: "2017",
        privateKey: fs.readFileSync("./dkim-2017.pem", "utf8"),
      },
      {
        domainName: "example.com",
        keySelector: "2016",
        privateKey: fs.readFileSync("./dkim-2016.pem", "utf8"),
      },
    ],
    cacheDir: false, // disable disk caching
  },
});
```

--------------------------------

### Nodemailer Address Formats Example

Source: https://nodemailer.com/message/addresses

Demonstrates how to use different formats for email addresses (from, to, cc, bcc) in a Nodemailer message object. Supports single strings, comma-separated strings, arrays of strings, and mixed arrays of strings and objects.

```javascript
const message = {
  // Single formatted address string
  from: '"Example Sender" <sender@example.com>',

  // Comma-separated string with multiple recipients
  to: 'foobar@example.com, "Ноде Майлер" <bar@example.com>, "Name, User" <baz@example.com>',

  // Array of address strings
  cc: [
    "first@example.com",
    '"Ноде Майлер" <second@example.com>',
    '"Name, User" <third@example.com>'
  ],

  // Mixed array: strings and address objects together
  bcc: [
    "hidden@example.com",
    {
      name: "Майлер, Ноде",
      address: "another@example.com"
    }
  ]
};
```

--------------------------------

### Create SMTP Server Instance

Source: https://nodemailer.com/extras/smtp-server

Instantiate the SMTPServer with optional configuration options. This prepares the server to listen for connections.

```javascript
const server = new SMTPServer(options);  

```

--------------------------------

### MailParser Initialization and Usage

Source: https://nodemailer.com/extras/mailparser

Demonstrates how to instantiate MailParser, pipe a source stream to it, and handle 'data', 'headers', and 'end' events for attachments, text bodies, and headers.

```APIDOC
## MailParser (stream API)

For processing large messages without loading everything into memory, use the `MailParser` class directly:

```javascript
const { MailParser } = require("mailparser");  
  
const parser = new MailParser(options);  
sourceStream.pipe(parser);
```

`MailParser` is a `Transform` stream in **object mode** that emits two types of objects via the `'data'` event:
  1. **`{ type: 'attachment', ... }`**- Emitted for each attachment. The `content` property is a **Readable stream** that you must consume.
  2. **`{ type: 'text', html, text, textAsHtml }`**- Emitted once after all parts are processed, containing the message bodies.

### Header events
`MailParser` also emits two events for accessing email headers:
  1. **`'headers'`**- Emits a `Map` of parsed header keys to their values. Fired once when headers are fully parsed.
  2. **`'headerLines'`**- Emits an `Array` of objects with `key` and `line` properties containing the raw header data.

```javascript
parser.on("headers", (headers) => {
  console.log("Subject:", headers.get("subject"));
  console.log("From:", headers.get("from"));
});
```

### Stream options
The following options can be passed to both `simpleParser()` and `new MailParser()`:

| Option | Default | Description |
|---|---|---|
| `skipHtmlToText` | `false` | Do not generate `text` from HTML when no plain text part exists |
| `maxHtmlLengthToParse` | `Infinity` | Maximum HTML length (in characters of the decoded body) to convert to text. If exceeded, an `'error'` event is emitted (rejecting `simpleParser`) and the HTML part is dropped from the output |
| `formatDateString` | `undefined` | Custom function to format Date objects as strings |
| `skipImageLinks` | `false` | Keep `cid:` image URLs as-is instead of converting to data URIs |
| `skipTextToHtml` | `false` | Do not generate `textAsHtml` from plain text |
| `skipTextLinks` | `false` | Do not auto-detect and linkify URLs in plain text |
| `keepDeliveryStatus` | `false` | Treat `message/delivery-status` parts as attachments instead of text |
| `checksumAlgo` | `'md5'` | Hash algorithm for attachment checksums (e.g., `'sha256'`, `'sha512'`) |
| `Iconv` | `iconv-lite` | Alternative iconv implementation for character set conversion |
| `keepCidLinks` | `false` | **simpleParser only** - Keep `cid:` URLs instead of converting to data URIs (same as `skipImageLinks: true`) |

### Attachment stream object (`type === 'attachment'`)
When using the `MailParser` stream API, attachment objects have the same properties as described above, with these important differences:
  * **`content`**is a**Readable stream** , not a Buffer. You must consume this stream to get the attachment data.
  * **You must call`attachment.release()`** when you are finished processing the attachment. Parsing is paused until every attachment is released, which prevents memory from growing unbounded.
  * **`checksum`**and**`size`**are populated only after the`content` stream has been fully consumed — read them after the stream's `'end'` event.

```javascript
const fs = require("fs");  
  
parser.on("data", (part) => {
  if (part.type === "attachment") {
    console.log("Saving attachment:", part.filename);

    // Pipe the attachment stream to a file
    const output = fs.createWriteStream(part.filename);
    part.content.pipe(output);

    // Release the attachment when the stream finishes
    output.on("finish", () => {
      part.release();
    });
  }
});

parser.on("end", () => {
  console.log("Parsing complete");
});
```
```

--------------------------------

### TLS and STARTTLS Configuration

Source: https://nodemailer.com/extras/smtp-server

Enables TLS or STARTTLS by providing a valid certificate using the key, cert, and ca options. Uses a self-signed certificate for localhost if not provided.

```javascript
const fs = require("fs");
const server = new SMTPServer({
  secure: true,
  key: fs.readFileSync("private.key"),
  cert: fs.readFileSync("server.crt"),
});
server.listen(465);

```

--------------------------------

### connect(callback)

Source: https://nodemailer.com/extras/smtp-connection

Establishes a connection to the SMTP server. The callback is invoked once, with no arguments, when the connection is ready for commands. Errors are emitted on the 'error' event.

```APIDOC
## connect(callback)

### Description
Establishes a connection to the SMTP server. The callback is invoked once, with no arguments, when the connection is ready for commands (after the initial greeting and EHLO/HELO handshake). Connection failures (DNS, TCP, TLS, greeting errors) are not passed to this callback — they are emitted on the 'error' event, so always attach an error listener.

### Method
POST

### Endpoint
/connect

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
connection.on("error", (err) => {
  console.error("Connection failed:", err);
});

connection.connect(() => {
  console.log("Connected!");
});
```

### Response
#### Success Response (200)
Callback is invoked with no arguments upon successful connection.

#### Response Example
```javascript
// Callback is invoked
console.log("Connected!");
```
```

--------------------------------

### Enhanced Status Codes Example

Source: https://nodemailer.com/extras/smtp-server

Illustrates the format of SMTP responses with and without enhanced status codes.

```text
250 2.1.0 Accepted        <- Enhanced status code: 2.1.0
550 5.1.1 Mailbox unavailable <- Enhanced status code: 5.1.1
```

--------------------------------

### Import SMTPConnection Module

Source: https://nodemailer.com/extras/smtp-connection

Import the SMTPConnection module from Nodemailer. This module is included with Nodemailer, so no additional packages need to be installed.

```javascript
const SMTPConnection = require("nodemailer/lib/smtp-connection");
```

--------------------------------

### Create SMTPConnection Instance

Source: https://nodemailer.com/extras/smtp-connection

Instantiate the SMTPConnection with an options object to configure the connection parameters.

```javascript
const connection = new SMTPConnection(options);
```

--------------------------------

### Example Nodemailer Error Object

Source: https://nodemailer.com/errors

Illustrates the structure of an error object produced by Nodemailer, including message, code, command, response, and responseCode.

```javascript
{
  message: 'Invalid login: 535 5.7.8 Authentication failed',
  code: 'EAUTH',
  command: 'AUTH PLAIN',
  response: '535 5.7.8 Authentication failed',
  responseCode: 535
}
```

--------------------------------

### Custom Logger Implementation for Nodemailer

Source: https://nodemailer.com/smtp

Demonstrates how to wrap a custom logger (like Pino) to be compatible with Nodemailer's logging interface. This allows for centralized logging with custom configurations.

```javascript
const smtpLogger = {};

// Set up logger wrapper for each log level
for (let level of ['trace', 'debug', 'info', 'warn', 'error', 'fatal']) {
    smtpLogger[level] = (data, message, ...args) => {
        if (args && args.length) {
            message = util.format(message, ...args);
        }
        data.msg = message;
        data.src = 'nodemailer';
        if (typeof pinoLogger[level] === 'function') {
            pinoLogger[level](data);
        } else {
            pinoLogger.debug(data);
        }
    };
}

nodemailer.createTransport({
    // ... other options
    logger: smtpLogger
})
```

--------------------------------

### Enabling REQUIRETLS Extension

Source: https://nodemailer.com/errors

Example of setting `requireTLSExtensionEnabled: true` for secure email delivery. Ensure your SMTP server supports the REQUIRETLS extension (RFC 8689).

```javascript
const message = {  
  from: "sender@example.com",  
  to: "recipient@example.com",  
  subject: "Secure message",  
  text: "This requires TLS throughout delivery",  
  requireTLSExtensionEnabled: true, // Requires server support  
};  
```

--------------------------------

### Register Custom Proxy Handler

Source: https://nodemailer.com/smtp/proxies

Register a custom handler for a specific proxy URL scheme. This example shows how to connect to a custom proxy and perform a handshake.

```javascript
const transporter = nodemailer.createTransport({
  host: "smtp.example.com",
  port: 465,
  secure: true,
  proxy: "myproxy://127.0.0.1:9999",
});

// Register a handler for the "myproxy:" URL scheme
transporter.set("proxy_handler_myproxy", (proxy, options, done) => {
  const net = require("net");

  console.log("Connecting to proxy at %s:%s", proxy.hostname, proxy.port);

  const socket = net.connect(proxy.port, proxy.hostname, () => {
    // Perform any custom handshake with your proxy here...

    // Return the established socket to Nodemailer
    done(null, { connection: socket });
  });
});

```

--------------------------------

### Password-based Authentication (PLAIN/LOGIN)

Source: https://nodemailer.com/extras/smtp-server

Implement password-based authentication by comparing the provided username and password against expected credentials. Reject with an error if they do not match, otherwise accept the login.

```javascript
onAuth(auth, session, callback) {
  if (auth.username !== "alice" || auth.password !== "s3cr3t") {
    return callback(new Error("Invalid username or password"));
  }
  callback(null, { user: auth.username });
}
```

--------------------------------

### Handling EURLACCESS with Direct Content Fetching

Source: https://nodemailer.com/errors

Shows how to avoid EURLACCESS errors by fetching URL content directly and passing it as a Buffer. This is necessary when `disableUrlAccess` is enabled.

```javascript
// This will throw EURLACCESS if disableUrlAccess is true  
const message = {  
  attachments: [{ href: "https://example.com/file.pdf" }],  
};  
```

--------------------------------

### Full 3-Legged OAuth2 Setup with Auto-Refresh

Source: https://nodemailer.com/smtp/oauth2

Suitable for scenarios where you have OAuth2 credentials and a refresh token. Nodemailer automatically handles refreshing the access token when it expires.

```javascript
let transporter = nodemailer.createTransport({
  host: "smtp.gmail.com",
  port: 465,
  secure: true,
  auth: {
    type: "OAuth2",
    user: "user@example.com",
    clientId: "000000000000-xxx.apps.googleusercontent.com",
    clientSecret: "XxxxxXXxX0xxxxxxxx0XXxX0",
    refreshToken: "1/XXxXxsss-xxxXXXXXxXxx0XXXxxXXx0x00xxx",
    accessToken: "ya29.Xx_XX0xxxxx-xX0X0XxXXxXxXXXxX0x",
    expires: 1484314697598,
  },
});
```

--------------------------------

### Create SMTP Transporter

Source: https://nodemailer.com/

Configure and create a Nodemailer transporter using SMTP settings. This is the first step to sending emails. Ensure you have Node.js v6.0.0 or later installed.

```javascript
const nodemailer = require("nodemailer");  
  
// Create a transporter using SMTP  
const transporter = nodemailer.createTransport({
  host: "smtp.example.com",  
  port: 587,  
  secure: false, // use STARTTLS (upgrade connection to TLS after connecting)  
  auth: {
    user: process.env.SMTP_USER,
    pass: process.env.SMTP_PASS,
  },
});  

```
Tokens:
Raw