Message configuration

The following are the possible fields of an email message:

Common fields

  • from - The email address of the sender. All email addresses can be plain sender@server.com or formatted '“Sender Name” sender@server.com', see Address object for details
  • to - Comma separated list or an array of recipients email addresses that will appear on the To: field
  • cc - Comma separated list or an array of recipients email addresses that will appear on the Cc: field
  • bcc - Comma separated list or an array of recipients email addresses that will appear on the Bcc: field
  • subject - The subject of the email
  • text - The plaintext version of the message as an Unicode string, Buffer, Stream or an attachment-like object ({path: ‘/var/data/…'})
  • html - The HTML version of the message as an Unicode string, Buffer, Stream or an attachment-like object ({path: ‘http://…'})
  • attachments - An array of attachment objects (see Using attachments for details). Attachments can be used for embedding images as well.

A large majority of emails sent look a lot like this, using only a few basic fields:

var message = {
  from: "sender@server.com",
  to: "receiver@sender.com",
  subject: "Message title",
  text: "Plaintext version of the message",
  html: "<p>HTML version of the message</p>",
};
All text fields (email addresses, plaintext body, html body, attachment filenames) use UTF-8 as the encoding. Attachments are streamed as binary.

More advanced fields

Routing options
  • sender - An email address that will appear on the Sender: field (always prefer from if you’re not sure which one to use)
  • replyTo - An email address that will appear on the Reply-To: field
  • inReplyTo - The Message-ID this message is replying to
  • references - Message-ID list (an array or space separated string)
  • envelope - optional SMTP envelope, if auto generated envelope is not suitable (see SMTP envelope for details)
Content options
  • attachDataUrls – if true then convert data: images in the HTML content of this message to embedded attachments
  • watchHtml - Apple Watch specific HTML version of the message. Latest watches have no problems rendering text/html content so watchHtml is most probably never seen by the recipient
  • amp - AMP4EMAIL specific HTML version of the message, same usage as with text and html. See AMP example below for usage or this blogpost for sending and rendering
When using `amp` then make sure it is a full and valid AMP4EMAIL document, otherwise the displaying email client most probably falls back to `html` and ignores the `amp` part. Validate your AMP4EMAIL content [here](https://validator.ampproject.org/#htmlFormat=AMP4EMAIL)
  • icalEvent – iCalendar event to use as an alternative. See details here
  • alternatives - An array of alternative text contents (in addition to text and html parts) (see Using alternative content for details)
  • encoding - identifies encoding for text/html strings (defaults to ‘utf-8’, other values are ‘hex’ and ‘base64’)
  • raw - existing MIME message to use instead of generating a new one. See details here
  • textEncoding - force content-transfer-encoding for text values (either quoted-printable or base64). By default the best option is detected (for lots of ascii use quoted-printable, otherwise base64)
Header options
  • priority - Sets message importance headers, either ‘high’, ‘normal’ (default) or ‘low’.
  • headers - An object or array of additional header fields (e.g. {“X-Key-Name”: “key value”} or [{key: “X-Key-Name”, value: “val1”}, {key: “X-Key-Name”, value: “val2”}]). Read more about custom headers here
  • messageId - optional Message-Id value, random value will be generated if not set
  • date - optional Date value, current UTC string will be used if not set
  • list - helper for setting List-* headers (see more here)
Security options
  • disableFileAccess if true, then does not allow to use files as content. Use it when you want to use JSON data from untrusted source as the email. If an attachment or message node tries to fetch something from a file the sending returns an error. If this field is also set in the transport options, then the value in mail data is ignored
  • disableUrlAccess if true, then does not allow to use Urls as content. If this field is also set in the transport options, then the value in mail data is ignored
var message = {
    ...,
    headers: {
        'My-Custom-Header': 'header value'
    },
    date: new Date('2000-01-01 00:00:00')
};
**Memory leak warning!** When using readable streams as content and sending fails then Nodemailer does not abort the already opened but not yet finished stream, you need to do this yourself. Nodemailer only closes the streams it has opened itself (eg. file paths, URLs)
var htmlstream = fs.createReadStream("content.html");
transport.sendMail({ html: htmlstream }, function (err) {
  if (err) {
    // check if htmlstream is still open and close it to clean up
  }
});
AMP example
let message = {
    from: 'Nodemailer <example@nodemailer.com>',
    to: 'Nodemailer <example@nodemailer.com>',
    subject: 'AMP4EMAIL message',
    text: 'For clients with plaintext support only',
    html: '<p>For clients that do not support AMP4EMAIL or amp content is not valid</p>',
    amp: `<!doctype html>
    <html ⚡4email>
      <head>
        <meta charset="utf-8">
        <style amp4email-boilerplate>body{visibility:hidden}</style>
        <script async src="https://cdn.ampproject.org/v0.js"></script>
        <script async custom-element="amp-anim" src="https://cdn.ampproject.org/v0/amp-anim-0.1.js"></script>
      </head>
      <body>
        <p>Image: <amp-img src="https://cldup.com/P0b1bUmEet.png" width="16" height="16"/></p>
        <p>GIF (requires "amp-anim" script in header):<br/>
          <amp-anim src="https://cldup.com/D72zpdwI-i.gif" width="500" height="350"/></p>
      </body>
    </html>`
}