Repository files navigation

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


Notice for v0.x users – Do not upgrade Nodemailer from 0.7 or lower. You can continue to use the 0.7 branch as long as you like. See the documentation for 0.7here.

• Unicode to use any characters
• Windows – you can install it withnpm on Windows just like any other module, there are no compiled dependencies. Use it from Azure or from your Windows box hassle free.
• HTML content as well asplain text alternative
• Attachments (including attachmentstreaming for sending larger files)
• Embedded images in HTML
• Secure e-mail delivery usingSSL/STARTTLS
• Differenttransport methods, either using built in transports or from external plugins
• CustomPlugin support for manipulating messages (add DKIM signatures, use markdown content instead of HTML etc.)
• SaneXOAUTH2 login with automatic access token generation (and feedback about the updated tokens)

If you want to support with Bitcoins, then my wallet address is15Z8ADxhssKUiwP3jbbqJwA21744KMCfTM

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

varnodemailer=require('nodemailer');// create reusable transporter object using SMTP transportvartransporter=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 symbolsvarmailOptions={from:'Fred Foo ✔ <foo@blurdybloop.com>',// sender addressto:'bar@blurdybloop.com, baz@blurdybloop.com',// list of receiverssubject:'Hello ✔',// Subject linetext:'Hello world ✔',// plaintext bodyhtml:'<b>Hello world ✔</b>'// html body};// send mail with defined transport objecttransporter.sendMail(mailOptions,function(error,info){if(error){returnconsole.log(error);}console.log('Message sent: '+info.response);});

You may need to"Allow Less Secure Apps" in your gmail account (it's all the way at the bottom). You also may need to"Allow access to your Google account"

Seenodemailer-smtp-transport for SMTP configuration options andnodemailer-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 particulartransport mechanism.

Install with npm

npm install nodemailer

To send e-mails you need a transporter object

vartransporter=nodemailer.createTransport(transport[,defaults])

Where

• transporter is going to be an object that is able to send mail
• transport is a transport mechanism. If it is not setnodemailer-direct-transport transport is used. If it is a regular objectnodemailer-smtp-transport is used and the value is passed as SMTP configuration.
• defaults is an object that defines default values for mail options (available since Nodemailer v1.10.0)

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.

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

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

Usingdirect 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.

See SMTPconfiguration options here

varnodemailer=require('nodemailer');vartransporter=nodemailer.createTransport({service:'gmail',auth:{user:'sender@gmail.com',pass:'password'}},{// default values for sendMail methodfrom:'sender@address',headers:{'My-Awesome-Header':'123'}});transporter.sendMail({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. Usenodemailer-smtp-pool if you need to send a large amount of e-mails.

For sending bulk mail using Nodemailer see therecommendations below

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

The following example usesnodemailer-ses-transport (Amazon SES).

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

Built in

• nodemailer-smtp-transport for sending messages using a SMTP service
• nodemailer-direct-transport for sending messages directly to recipients MX servers (zero configuration needed but unreliable)

Install as dependencies

• nodemailer-smtp-pool for sending messages to SMTP using pooled connections
• nodemailer-ses-transport for sending messages to AWS SES
• nodemailer-sendmail-transport for piping messages to thesendmail command
• nodemailer-stub-transport is just for returning messages, most probably for testing purposes
• nodemailer-pickup-transport for storing messages to pickup folders
• nodemailer-sparkpost-transport for sending messages through SparkPost's Web API
• nodemailer-sendgrid-transport for sending messages through SendGrid's Web API
• nodemailer-sailthru-transport for sending messages through Sailthru's Web API
• nodemailer-mandrill-transport for sending messages through Mandrill's Web API
• add yours (see transport api documentationhere)

• nodemailer-markdown to use markdown for the content
• nodemailer-dkim to sign messages with DKIM
• nodemailer-html-to-text to auto generate plaintext content from html
• nodemailer-express-handlebars to auto generate html emails from handlebars/mustache templates
• nodemailer-plugin-inline-base64 to convert base64 images to attachments
• nodemailer-hashcash to generatehashcash headers
• add yours (see plugin api documentationhere)

Once you have a transporter object you can send mail

transporter.sendMail(data[,callback])

Where

• data defines the mail content (seee-mail message fields below)
• callback is an optional callback function to run once the message is delivered or it failed
  • err is the error object if message failed
  • info includes the result, the exact format depends on the transport mechanism used
    • info.messageId most transportsshould return the final Message-Id value used with this property
    • info.envelope includes the envelope object for the message
    • info.accepted is an array returned by SMTP transports (includes recipient addresses that were accepted by the server)
    • info.rejected is an array returned by SMTP transports (includes recipient addresses that were rejected by the server)
    • info.pending is an array returned by Direct SMTP transport. Includes recipient addresses that were temporarily rejected together with the server response
    • response is a string returned by SMTP transports and includes the last SMTP response from the server

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

Ifcallback argument is not set then the method return a Promise object. Nodemailer itself does not use Promises internally but it wraps the return into a Promise for convenience.

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

• from - The e-mail address of the sender. All e-mail addresses can be plain'sender@server.com' or formatted'Sender Name <sender@server.com>', seehere for details
• sender - An e-mail address that will appear on theSender: field
• to - Comma separated list or an array of recipients e-mail addresses that will appear on theTo: field
• cc - Comma separated list or an array of recipients e-mail addresses that will appear on theCc: field
• bcc - Comma separated list or an array of recipients e-mail addresses that will appear on theBcc: field
• replyTo - An e-mail address that will appear on theReply-To: field
• inReplyTo - The message-id this message is replying
• references - Message-id list (an array or space separated string)
• subject - The subject of the e-mail
• text - The plaintext version of the message as an Unicode string, Buffer, Stream or an object{path: '...'}
• html - The HTML version of the message as an Unicode string, Buffer, Stream or an object{path: '...'}
• watchHtml - Apple Watch specific HTML version of the message (experimental)
• 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"}])
• attachments - An array of attachment objects (seebelow for details)
• alternatives - An array of alternative text contents (in addition to text and html parts) (seebelow for details)
• envelope - optional SMTP envelope, if auto generated envelope is not suitable (seebelow for details)
• 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
• encoding - optional transfer encoding for the textual parts

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

Attachment object consists of the following properties:

• filename - filename to be reported as the name of the attached file, use of unicode is allowed
• cid - optional content id for using inline images in HTML message source
• content - String, Buffer or a Stream contents for the attachment
• encoding - If set andcontent is string, then encodes the content to a Buffer using the specified encoding. Example values:base64,hex,binary etc. Useful if you want to use binary attachments in a JSON formatted e-mail object.
• path - path to a file or an URL (data uris are allowed as well) if you want to stream the file instead of including it (better for larger attachments)
• contentType - optional content type for the attachment, if not set will be derived from thefilename property
• contentDisposition - optional content disposition type for the attachment, defaults to 'attachment'

Warning about stream errors –If an error occurs with an input stream, eg. an attachment from an URL fails to load, then message generation is not rejected. Instead, the error message gets written as the attachment contents.

Attachments can be added as many as you want.

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

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 asattachment objects. The difference between an attachment and an alternative is the fact that attachments are placed intomultipart/mixed ormultipart/related parts of the message white alternatives are placed intomultipart/alternative part.

Usage example:

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

Alternatives can be added as many as you want.

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

foobar@blurdybloop.com

or with formatted name (includes unicode support)

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

Notice that all address fields (evenfrom) are comma separated lists, so if you want to use a comma in the name part, make sure you enclose the name in double quotes:"Майлер, Ноде" <foobar@blurdybloop.com>

or as an address object (in this case you do not need to worry about the formatting, no need to use quotes etc.)

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

All address fields accept comma separated list of e-mails or an array ofe-mails or an array of comma separated list of e-mails or address objects - 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>'],bcc: ['foobar@blurdybloop.com', {name: 'Майлер, Ноде', address: 'foobar@blurdybloop.com'}]...

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

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

SMTP envelope is usually auto generated fromfrom,to,cc andbcc fields butif for some reason you want to specify it yourself, you can do it withenvelope property.

envelope is an object with the following params:from,to,cc andbcc just likewith 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 theenvelope object, for example SES ignores it and uses the data from the From:, To: etc. headers.

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 samecid value must be used as the image URL in HTML (usingcid: as the URL protocol, see example below).

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

varmailOptions={    ...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}]}

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 modifyhtml content, add new headers etc. Example:nodemailer-markdown that allows you to usemarkdown source instead oftext andhtml.
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.

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

transporter.use(step,pluginFunc)

Where

• transporter is a transport object created withcreateTransport
• step is a string, either 'compile' or 'stream' that defines when the plugin should be hooked
• pluginFunc is a function that takes two arguments: the mail object and a callback function

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:

• data is the mail data object that is passed to thesendMail method
• message is theBuildMail object of the message. This is available for the 'stream' step and for the transport but not for 'compile'.
• resolveContent is a helper function for converting Nodemailer compatible stream objects into Strings or Buffers

If your plugin needs to get the full value of a param, for example the String value for thehtml content, you can useresolveContent() to convert Nodemailercompatible content objects to Strings or Buffers.

data.resolveContent(obj,key,callback)

Where

• obj is an object that has a property you want to convert to a String or a Buffer
• key is the name of the property you want to convert
• callback is the callback function with (err, value) wherevalue is either a String or Buffer, depending on the input

Example

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

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

This is really straightforward, your plugin can modify themail.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 thesendMail callback.

Example

The following plugin checks iftext value is set and if not convertshtml value totext by removing all html tags.

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

Seeplugin-compile.js for a working example.

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

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

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

Example

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

vartransformer=new(require('stream').Transform)();transformer._transform=function(chunk,encoding,done){// replace all tabs with spaces in the stream chunkfor(vari=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 streammail.message.transform(transformer);callback();});

Seeplugin-stream.js for a working example.

Additionally you might be interested in themessage.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){varaddresses=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 are objects that have a methodsend and properiesname andversion. Additionally, if the transport object is an Event Emitter, 'log' events are piped through Nodemailer. A transport object is passed to thenodemailer.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 withmail.message.createReadStream()

Callback function should return aninfo object as the second arugment. This info object should containmessageId 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){varinput=mail.message.createReadStream();varmessageId=(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 aclose 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});

Seeminimal-transport.js for a working example.

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). When using this method make sure to enable the required functionality by completing the "captcha enable". Without this, less secure connections won't work.

To prevent having login issues you should either use XOAUTH2 (see detailshere) or use another provider and preferably a dedicated one likeMailgun orSendGrid or any other. Usually these providers have free plans available that are comparable to the daily sending limits of Gmail. Gmail has a limit of 500 recipients a day (a message with oneTo and oneCc 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.

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

1. Use a dedicated SMTP provider likeSendGrid orMailgun or any other. Do not use services that offer SMTP as a sideline or for free (that's 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 exampleRabbitMQ 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. Usenodemailer-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. SetmaxMessages option toInfinity 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. SetmaxConnections to whatever your system can handle. There might be limits to this on the receiving side, so do not set it toInfinity, 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.

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

The Nodemailer logo was designed bySven Kristjansen.