DOCSEARCHbyAlgolia
Submit Docs

Nodemailer Documentation

website·Indexed 39 days ago

https://nodemailer.com

A module for Node.js applications to send emails. Features include support for SMTP, Amazon SES, Sendmail, and Stream transports, as well as DKIM signing, OAuth2 authentication, and a streaming email parser called MailParser. The documentation covers message configuration, transport options, and guides for integrating with services like Gmail and Ethereal.

Tokens
41.3K
Snippets
173
Records
270
Agent score
74%

What's inside Nodemailer

  1. Overview of Ethereal for email testing

    Ethereal is a free fake SMTP service designed for testing Nodemailer and other email-sending applications. It captures sent messages and displays them in a web interface, but ensures they are never delivered to real recipients. It is ideal for development and debugging because it requires no signup and provides instant previews of emails.

  2. Embed iCalendar events using the icalEvent option

    Nodemailer allows embedding an iCalendar (.ics) file directly in an email. This enables interactive controls like 'Add to calendar' or 'Accept/Decline' in clients like Gmail, Outlook, and Apple Mail.

    Important: Nodemailer does not generate the .ics content. You must use a library such as ical-generator or ics to create the valid iCalendar data before passing it to Nodemailer.

    For maximum compatibility across email clients, it is recommended to keep the message simple: include only text, html, and a single icalEvent. Avoid adding other file attachments to calendar invitation emails.

  3. Validate email authentication with mailauth

    The mailauth library provides tools to validate and generate email authentication records, including SPF, DKIM, DMARC, ARC, and BIMI, to improve email deliverability and verify authenticity.

  4. Manage emails via IMAP with ImapFlow

    ImapFlow is a modern, Promise-based IMAP client for Node.js used for reading and managing emails on any IMAP server.

  5. Understand the Nodemailer SMTP response object

    When using the SMTP transport, the sendMail method returns an info object containing details about the delivery. Note that a message is considered 'sent' if at least one recipient was accepted; you must check the rejected array to identify partial failures.
    // Properties available in the SMTP response object
{
  messageId: string,      // The Message-ID header value
  envelope: object,       // SMTP envelope addresses (from and to)
  accepted: string[],     // Recipient addresses accepted by the server
  rejected: string[],     // Recipient addresses rejected by the server
  rejectedErrors: any[],  // Error details for rejected recipients
  response: string,       // Final response string from SMTP server
  ehlo: string[],         // Server capability lines from EHLO response
  envelopeTime: number,   // ms spent on envelope exchange
  messageTime: number,     // ms spent streaming message body
  messageSize: number     // Size of transferred message in bytes
}

  6. Use email alternatives to provide multiple body formats

    Alternatives are different representations of the same email message (e.g., Markdown, machine-readable formats). Unlike attachments, which are downloadable files, alternatives are versions of the email body itself. The recipient's email client automatically selects and displays the best format it supports from a multipart/alternative container.

    For calendar invitations, use the dedicated icalEvent option instead of the alternatives array for better compatibility.

  7. Understand Nodemailer plugin lifecycle phases

    Nodemailer allows injecting custom logic at three distinct phases of a message's lifecycle:

    PhaseStageWhen it runsTypical uses
    Pre-processingcompileAfter the message object is created but before the MIME source is generatedTemplating, automatic plain-text alternatives, address validation
    ProcessingstreamAfter MIME compilation, while the message stream is being prepared for sendingInlining images, transforming HTML content
    SendingtransportWhen the message is ready to be deliveredCustom HTTP APIs, SMTP, SES, SparkPost

    Note: compile and stream plugins are registered via transporter.use(). The transport stage is not registered with use(); instead, a custom transport object is passed to nodemailer.createTransport().

  8. Manage SMTP sessions with SMTPConnection

    The SMTPConnection module is a low-level SMTP client used for establishing outbound SMTP connections. It is the foundation for Nodemailer's SMTP transport and is used when fine-grained control over the SMTP session lifecycle is required. It is included with Nodemailer and requires no additional installation.

  9. Reference the SMTPServer Session object

    The session object is passed to all callback handlers and contains metadata about the current connection:

    PropertyTypeDescription
    idStringUnique identifier for the connection.
    remoteAddressStringClient's IP address.
    clientHostnameStringReverse DNS hostname of the client.
    openingCommandStringThe greeting command sent (HELO, EHLO, or LHLO).
    hostNameAppearsAsStringHostname provided by the client in the greeting.
    envelopeObjectMail transaction data (mailFrom, rcptTo).
    useranyValue returned from onAuth after successful login.
    transactionNumberTransaction counter (1 for first message, etc.).
    transmissionTypeStringType string for Received: headers (e.g., SMTP, ESMTP).

  10. Build an SMTP server with smtp-server

    Use the smtp-server library to build a custom SMTP server in Node.js that can accept incoming email connections. This is ideal for creating custom mail servers, testing email workflows, or building applications that receive email.

  11. Turn email accounts into REST endpoints with EmailEngine

    EmailEngine is a self-hosted, commercial, source-available email API that converts Gmail, Microsoft 365, or IMAP accounts into REST endpoints. It handles OAuth2, token refresh, SMTP sending, and provides real-time updates via webhooks.

  12. Generate RFC 822 email messages with mailcomposer

    The mailcomposer library generates RFC 822-compliant email messages from JavaScript objects. This is useful for creating properly formatted MIME messages that are not sent immediately, such as for storing drafts or passing to another system. Note: This library ships inside the Nodemailer package.