Fork me on GitHub

Nodemailer

Send e-mails from Node.js – easy as cake!

Build Status NPM version

Upgrade warning

Do not upgrade Nodemailer from 0.7 or lower to 1.0 as there are breaking changes. You can continue to use the 0.7 branch as long as you like. See the documentation for 0.7 here.

Migration guide

See the migration guide from 0.7 to 1.0 in the 1.0 release blog post.

Notes and information

Nodemailer supports

Support Nodemailer development

Donate to author

If you want to support with Bitcoins, then my wallet address is 15Z8ADxhssKUiwP3jbbqJwA21744KMCfTM

TL;DR Usage Example

This is a complete example to send an e-mail with plaintext and HTML body

var nodemailer = require('nodemailer');

// create reusable transporter object using SMTP transport
var transporter = nodemailer.createTransport({
    service: 'Gmail',
    auth: {
        user: 'gmail.user@gmail.com',
        pass: 'userpass'
    }
});

// NB! No need to recreate the transporter object. You can use
// the same transporter object for all e-mails

// setup e-mail data with unicode symbols
var mailOptions = {
    from: 'Fred Foo ✔ <foo@blurdybloop.com>', // sender address
    to: 'bar@blurdybloop.com, baz@blurdybloop.com', // list of receivers
    subject: 'Hello ✔', // Subject line
    text: 'Hello world ✔', // plaintext body
    html: '<b>Hello world ✔</b>' // html body
};

// send mail with defined transport object
transporter.sendMail(mailOptions, function(error, info){
    if(error){
        console.log(error);
    }else{
        console.log('Message sent: ' + info.response);
    }
});

See nodemailer-smtp-transport for SMTP configuration options and nodemailer-wellknown for preconfigured service names (example uses 'gmail').

When using default SMTP transport, then you do not need to define transport type explicitly (even though you can), just provide the SMTP options and that's it. For anything else, see the docs of the particular transport mechanism.

Goals for 1.0

1. Move optional features out of core

Nodemailer 0.x is quite large and includes a ton of stuff that is not needed for most users. Sometimes it causes problems, for example when a feature that you do not even use requires some dependency to be installed that throws in your environment. If you only use SMTP to send e-mails you do not need the SES code and vice versa. The goal is achieved with a plugin system where you can install and load only these plugins that you actually require.

2. Gigabyte attachments

Version 1.0 is a total rewrite from the ground up and relying heavily on Streams2. This allows you to reliably send messages with gigabyte attachments even through a slow network connection without CPU or memory penalties. You probably never need it but it makes using smaller attachments more reliable as well.

Setting up

Install with npm

npm install nodemailer

To send e-mails you need a transporter object

var transporter = nodemailer.createTransport(transport)

Where

You have to create the transporter object only once. If you already have a transporter object you can use it to send mail as much as you like.

Examples

Use direct transport

In this case all e-mails are sent directly to the recipients MX server (using port 25)

var nodemailer = require('nodemailer');
var transporter = nodemailer.createTransport();
transporter.sendMail({
    from: 'sender@address',
    to: 'receiver@address',
    subject: 'hello',
    text: 'hello world!'
});

Using direct transport is not reliable as outgoing port 25 used is often blocked by default. Additionally mail sent from dynamic addresses is often flagged as spam. You should really consider using a SMTP provider.

Use the default SMTP transport

See SMTP configuration options here

var nodemailer = require('nodemailer');
var transporter = nodemailer.createTransport({
    service: 'gmail',
    auth: {
        user: 'sender@gmail.com',
        pass: 'password'
    }
});
transporter.sendMail({
    from: 'sender@address',
    to: 'receiver@address',
    subject: 'hello',
    text: 'hello world!'
});

Default SMTP transport is not suitable for large volume of e-mails new SMTP connection is established for every mail sent. Use nodemailer-smtp-pool if you need to send a large amout of e-mails.

For sending bulk mail using Nodemailer see the recommendations below

Use a transport plugin

See Available Transports for known transport plugins but there might be non listed plugins as well.

The following example uses nodemailer-ses-transport (Amazon SES).

var nodemailer = require('nodemailer');
var ses = require('nodemailer-ses-transport');
var transporter = nodemailer.createTransport(ses({
    accessKeyId: 'AWSACCESSKEY',
    secretAccessKey: 'AWS/Secret/key'
}));
transporter.sendMail({
    from: 'sender@address',
    to: 'receiver@address',
    subject: 'hello',
    text: 'hello world!'
});

Available Transports

Built in

Install as dependencies

Available Plugins

Sending mail

Once you have a transporter object you can send mail

transporter.sendMail(data, callback)

Where

If the message includes several recipients then the message is considered sent if at least one recipient is accepted

E-mail message fields

The following are the possible fields of an e-mail message:

All text fields (e-mail addresses, plaintext body, html body) use UTF-8 as the encoding. Attachments are streamed as binary.

Attachments

Attachment object consists of the following properties:

Attachments can be added as many as you want.

var mailOptions = {
    ...
    attachments: [
        {   // utf-8 string as an attachment
            filename: 'text1.txt',
            content: 'hello world!'
        },
        {   // binary buffer as an attachment
            filename: 'text2.txt',
            content: new Buffer('hello world!','utf-8')
        },
        {   // file on disk as an attachment
            filename: 'text3.txt',
            path: '/path/to/file.txt' // stream this file
        },
        {   // filename and content type is derived from path
            path: '/path/to/file.txt'
        },
        {   // stream as an attachment
            filename: 'text4.txt',
            content: fs.createReadStream('file.txt')
        },
        {   // define custom content type for the attachment
            filename: 'text.bin',
            content: 'hello world!',
            contentType: 'text/plain'
        },
        {   // use URL as an attachment
            filename: 'license.txt',
            path: 'https://raw.github.com/andris9/Nodemailer/master/LICENSE'
        },
        {   // encoded string as an attachment
            filename: 'text1.txt',
            content: 'aGVsbG8gd29ybGQh',
            encoding: 'base64'
        },
        {   // data uri as an attachment
            path: 'data:text/plain;base64,aGVsbG8gd29ybGQ='
        }
    ]
}

Alternatives

In addition to text and HTML, any kind of data can be inserted as an alternative content of the main body - for example a word processing document with the same text as in the HTML field. It is the job of the e-mail client to select and show the best fitting alternative to the reader. Usually this field is used for calendar events and such.

Alternative objects use the same options as attachment objects. The difference between an attachment and an alternative is the fact that attachments are placed into multipart/mixed or multipart/related parts of the message white alternatives are placed into multipart/alternative part.

Usage example:

var mailOptions = {
    ...
    html: '<b>Hello world!</b>',
    alternatives: [
        {
            contentType: 'text/x-web-markdown',
            content: '**Hello world!**'
        }
    ]
}

Alternatives can be added as many as you want.

Address Formatting

All the e-mail addresses can be plain e-mail addresses

foobar@blurdybloop.com

or with formatted name (includes unicode support)

"Ноде Майлер" <foobar@blurdybloop.com>

or as an address object

{
    name: 'Ноде Майлер',
    address: 'foobar@blurdybloop.com'
}

To, Cc and Bcc fields accept comma separated list of e-mails or an array of e-mails or an array of comma separated list of e-mails - use it as you like. Formatting can be mixed.

...,
to: 'foobar@blurdybloop.com, "Ноде Майлер" <bar@blurdybloop.com>, "Name, User" <baz@blurdybloop.com>',
cc: ['foobar@blurdybloop.com', '"Ноде Майлер" <bar@blurdybloop.com>, "Name, User" <baz@blurdybloop.com>']
...

You can even use unicode domains, these are automatically converted to punycode

'"Unicode Domain" <info@müriaad-polüteism.info>'

SMTP envelope

SMTP envelope is usually auto generated from from, to, cc and bcc fields but if for some reason you want to specify it yourself, you can do it with envelope property.

envelope is an object with the following params: from, to, cc and bcc just like with regular mail options. You can also use the regular address format, unicode domains etc.

mailOptions = {
    ...,
    from: 'mailer@kreata.ee',
    to: 'daemon@kreata.ee',
    envelope: {
        from: 'Daemon <deamon@kreata.ee>',
        to: 'mailer@kreata.ee, Mailer <mailer2@kreata.ee>'
    }
}

Not all transports can use the envelope object, for example SES ignores it and uses the data from the From:, To: etc. headers.

Using Embedded Images

Attachments can be used as embedded images in the HTML body. To use this feature, you need to set additional property of the attachment - cid (unique identifier of the file) which is a reference to the attachment file. The same cid value must be used as the image URL in HTML (using cid: as the URL protocol, see example below).

NB! the cid value should be as unique as possible!

var mailOptions = {
    ...
    html: 'Embedded image: <img src="cid:unique@kreata.ee"/>',
    attachments: [{
        filename: 'image.png',
        path: '/path/to/file',
        cid: 'unique@kreata.ee' //same cid value as in the html img src
    }]
}

Plugin system

There are 3 stages a plugin can hook to

  1. 'compile' is the step where e-mail data is set but nothing has been done with it yet. At this step you can modify mail options, for example modify html content, add new headers etc. Example: nodemailer-markdown that allows you to use markdown source instead of text and html.
  2. 'stream' is the step where message tree has been compiled and is ready to be streamed. At this step you can modify the generated MIME tree or add a transform stream that the generated raw e-mail will be piped through before passed to the transport object. Example: nodemailer-dkim that adds DKIM signature to the generated message.
  3. Transport step where the raw e-mail is streamed to destination. Example: nodemailer-smtp-transport that streams the message to a SMTP server.

Including plugins

'compile' and 'stream' plugins can be attached with use(plugin) method

transporter.use(step, pluginFunc)

Where

Plugin API

All plugins (including transports) get two arguments, the mail object and a callback function.

Mail object that is passed to the plugin function as the first argument is an object with the following properties:

resolveContent()

If your plugin needs to get the full value of a param, for example the String value for the html content, you can use resolveContent() to convert Nodemailer compatible content objects to Strings or Buffers.

data.resolveContent(obj, key, callback)

Where

Example

function plugin(mail, callback){
    // if mail.data.html is a file or an url, it is returned as a Buffer
    mail.resolveContent(mail.data, 'html', function(err, html){
        if(err){
            return callback(err);
        }
        console.log('HTML contents: %s', html.toString());
        callback();
    });
};

'compile'

Compile step plugins get only the mail.data object but not mail.message in the mail argument of the plugin function. If you need to access the mail.message as well use 'stream' step instead.

This is really straightforward, your plugin can modify the mail.data object at will and once everything is finished run the callback function. If the callback gets an error object as an argument, then the process is terminated and the error is returned to the sendMail callback.

Example

The following plugin checks if text value is set and if not converts html value to text by removing all html tags.

transporter.use('compile', function(mail, callback){
    if(!mail.text && mail.html){
        mail.text = mail.html.replace(/<[^>]*>/g, ' ');
    }
    callback();
});

See plugin-compile.js for a working example.

'stream'

Streaming step is invoked once the message structure is built and ready to be streamed to the transport. Plugin function still gets mail.data but it is included just for the reference, modifying it should not change anything (unless the transport requires something from the mail.data, for example mail.data.envelope).

You can modify the mail.message object as you like, the message is not yet streaming anything (message starts streaming when the transport calls mail.message.createReadStream()).

In most cases you might be interested in the message.transform() method for applying transform streams to the raw message.

Example

The following plugin replaces all tabs with spaces in the raw message.

var transformer = new (require('stream').Transform)();
transformer._transform = function(chunk, encoding, done) {
    // replace all tabs with spaces in the stream chunk
    for(var i = 0; i < chunk.length; i++){
        if(chunk[i] === 0x09){
            chunk[i] = 0x20;
        }
    }
    this.push(chunk);
    done();
};

transporter.use('stream', function(mail, callback){
    // apply output transformer to the raw message stream
    mail.message.transform(transformer);
    callback();
});

See plugin-stream.js for a working example.

Additionally you might be interested in the message.getAddresses() method that returns the contents for all address fields as structured objects.

Example

The following plugin prints address information to console.

transporter.use('stream', function(mail, callback){
    var addresses = mail.message.getAddresses();
    console.log('From: %s', JSON.stringify(addresses.from));
    console.log('To: %s', JSON.stringify(addresses.to));
    console.log('Cc: %s', JSON.stringify(addresses.cc));
    console.log('Bcc: %s', JSON.stringify(addresses.bcc));
    callback();
});

Transports

Transports are objects that have a method send and properies name and version. Additionally, if the transport object is an Event Emitter, 'log' events are piped through Nodemailer. A transport object is passed to the nodemailer.createTransport(transport) method to create the transporter object.

transport.name

This is the name of the transport object. For example 'SMTP' or 'SES' etc.

transport.name = require('package.json').name;

transport.version

This should be the transport module version. For example '0.1.0'.

transport.version = require('package.json').version;

transport.send(mail, callback)

This is the method that actually sends out e-mails. The method is basically the same as 'stream' plugin functions. It gets two arguments: mail and a callback. To start streaming the message, create the stream with mail.message.createReadStream()

Callback function should return an info object as the second arugment. This info object should contain messageId value with the Message-Id header (without the surrounding < > brackets)

The following example pipes the raw stream to the console.

transport.send = function(mail, callback){
    var input = mail.message.createReadStream();
    var messageId = (mail.message.getHeader('message-id') || '').replace(/[<>\s]/g, '');
    input.pipe(process.stdout);
    input.on('end', function() {
        callback(null, {
            messageId: messageId
        });
    });
};

transport.close(args*)

If your transport needs to be closed explicitly, you can implement a close method.

This is purely optional feature and only makes sense in special contexts (eg. closing a SMTP pool).

Once you have a transport object, you can create a mail transporter out of it.

var nodemailer = require('nodemailer');
var transport = require('some-transport-method');
var transporter = nodemailer.createTransport(transport);
transporter.sendMail({mail data});

See minimal-transport.js for a working example.

Using Gmail

Even though Gmail is the fastest way to get started with sending emails, it is by no means a preferable solution unless you are using OAuth2 authentication. Gmail expects the user to be an actual user not a robot so it runs a lot of heuristics for every login attempt and blocks anything that looks suspicious to defend the user from account hijacking attempts. For example you might run into trouble if your server is in another geographical location – everything works in your dev machine but messages are blocked in production.

Additionally Gmail has came up with the concept of 'less secure' apps which is basically anyone who uses plain password to login to Gmail, so you might end up in a situation where one username can send (support for 'less secure' apps is enabled) but other is blocked (support for 'less secure' apps is disabled).

To prevent having login issues you should either use XOAUTH2 (see details here) or use another provider and preferably a dedicated one like Mailgun or SendGrid or any other. Usually these providers have free plans available that are compareable to the daily sending limits of Gmail. Gmail has a limit of 500 recipients a day (a message with one To and one Cc address counts as two messages since it has two recipients) for @gmail.com addresses and 2000 for Google Apps customers, larger SMTP providers usually offer about 200-300 recipients a day for free.

Delivering Bulk Mail

Here are some tips how to handle bulk mail, for example if you need to send 10 million messages at once (originally published as a blog post).

  1. Use a dedicated SMTP provider like SendGrid or Mailgun or any other. Do not use services that offer SMTP as a sideline or for free (thats Gmail or the SMTP of your homepage hosting company) to send bulk mail – you'll hit all the hard limits immediatelly or get labelled as spam. Basically you get what you pay for and if you pay zero then your deliverability is near zero as well. E-mail might seem free but it is only free to a certain amount and that amount certainly does not include 10 million e-mails in a short period of time.
  2. Use a dedicated queue manager, for example RabbitMQ for queueing the e-mails. Nodemailer creates a callback function with related scopes etc. for every message so it might be hard on memory if you pile up the data for 10 million messages at once. Better to take the data from a queue when there's a free spot in the connection pool (previously sent message returns its callback).
  3. Use nodemailer-smtp-pool transport. You do not want to have the overhead of creating a new connection and doing the SMTP handshake dance for every single e-mail. Pooled connections make it possible to bring this overhead to a minimum.
  4. Set maxMessages option to Infinity for the nodemailer-smtp-pool transport. Dedicated SMTP providers happily accept all your e-mails as long you are paying for these, so no need to disconnect in the middle if everything is going smoothly. The default value is 100 which means that once a connection is used to send 100 messages it is removed from the pool and a new connection is created.
  5. Set maxConnections to whatever your system can handle. There might be limits to this on the receiving side, so do not set it to Infinity, even 20 is probably much better than the default 5. A larger number means a larger amount of messages are sent in parallel.
  6. Use file paths not URLs for attachments. If you are reading the same file from the disk several million times, the contents for the file probably get cached somewhere between your app and the physical hard disk, so you get your files back quicker (assuming you send the same attachment to all recipients). There is nothing like this for URLs – every new message makes a fresh HTTP fetch to receive the file from the server.
  7. If the SMTP service accepts HTTP API as well you still might prefer SMTP and not the HTTP API as HTTP introduces additional overhead. You probably want to use HTTP over SMTP if the HTTP API is bulk aware – you send a message template and the list of 10 million recipients and the service compiles this information into e-mails itself, you can't beat this with SMTP.

License

Nodemailer is licensed under MIT license. Basically you can do whatever you want to with it


The Nodemailer logo was designed by Sven Kristjansen.