Message configuration

The following are the possible fields of an email message:

Commmon fields

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

var message = {
    from: [email protected]',
    to: [email protected]',
    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
  • 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
    }
});