Nodemailer v1.0 release

The initial Nodemailer version v0.1.0 was released more than 3 years ago in January 2011. It was Node.js v0.3 days back then and npm was just getting some traction, so Nodemailer had to be installed from Github at first. Nodemailer added support for npm with the next release, v0.1.1.

Over the years nothing radical has happened. Nodemailer has been slowly evolving and adding new features, with just one larger shakedown with the release of Nodemailer v0.3 where the code was split into smaller modules. The API has stayed mostly the same, applications written for Nodemailer v0.1.1 should work fine with Nodemailer v0.7.1 (provided these applications can run under newer Node.js versions).

All of this is going to change with the current release of Nodemailer v1.0. For the first time Nodemailer is introducing backwards incompatible changes. This is needed to reduce complexity in code and make it more maintainable. Years of piling up functions have made Nodemailer not the most ideal code base. So something had to be changed to keep the sanity of the project.

The updated module is a total rewrite and shares nearly nothing with the previous version. A lot of the used code is new but a lot is ported from emailjs.org which is an email toolkit for browsers and is maintained by Whiteout.io.

Some API changes are purely cosmetic (for example using filename instead of fileName), some features are moved from core to external plugins that need to be installed separately (for example most of the transports) and some have been removed completely (like the generateTextFromHTML option). See below for the migration guide.

Moving functionality out of the core

To make it possible to add support for these removed features Nodemailer v1.0 introduces a simple plugin API. For example if you really need the feature that was provided by generateTextFromHTML option, you can create a plugin for it or use an existing one if someone else has already done it.

This should also ease building templating modules. As an example, the plugin nodemailer-markdown allows to use markdown instead of html or text as the message body and it also adds any referenced image as an attachment to the generated email. This feature is not supported by Nodemailer natively, but the support is gained once the plugin is attached to the Nodemailer transporter object.

Nodemailer 0.7 was quite large and included a ton of stuff that is not needed for most users. Sometimes it caused problems, for example when a feature that you didn't even need required some dependency to be installed that throwed in your environment. If you only use SMTP to send emails you do not need the SES code and vice versa.

Improved stability

Nodemailer v1.0 is Streams2 aware. It means that basically everything from the start to final delivery is handled by streams with the added benefit of an actually working back-pressure system. If your tcp is slow, then an attachment file is not read from the disk with full speed.

Nodemailer is still not entirely suitable for mass scale mailing but should handle occasional surge of sending several thousands emails, each including several megabytes (or even gigabytes – though why would anyone want to do this?) attachments with ease. Nodemailer is not suitable for mass scale mostly because every message gets its own callback and if you want to send a million emails at once (for example, with the help of a for loop), you're going to end up with a million queued callbacks with related scopes, email data and such. There are probably more efficient tools for such tasks.

Semantic versioning

From now on Nodemailer is going to follow the semantic versioning guide. New features bump the minor version and backwards incompatible changes are going to bump the major one. Bugfixes and such are going to bump the patch version.

Migration guide

E-mail message fields

  • Address fields allow mixing arrays with comma separated strings. You can also use {name: 'name', address: 'address'} objects instead of just strings for addresses. For example, this is a valid To: value:
[
    '[email protected], [email protected]',
    'Name <[email protected]>',
    {name: 'name', address: '[email protected]'}
]
  • generateTextFromHTML is removed (use nodemailer-html-to-text plugin instead)
  • charset is removed
  • dsn is removed
  • html and text take unicode strings, Buffer objects, Stream objects and attachment objects ({path: 'message.html'}) as the values.
  • headers does not support Objects as values (an object is not automatically JSONized anymore)

Attachment fields

  • fileName is now filename
  • filePath is now path
  • contents is now content
  • streamSource is dropped, use content instead
  • content accepts unicode strings, Buffer objects and Stream objects
  • Streams do not need to be explicitly paused, this is handled by the Streams2 flow mechanism

Alternatives

Uses the same structure as attachments so you can use Streams or files for the content.

DKIM

DKIM signing is not built in and there is no useDKIM() method anymore. Instead you can use the nodemailer-dkim plugin to add signing support. DKIM is still not efficient, as it requires the entire message to be buffered before it can be signed, so beware large attachments when using DKIM.

Transports

Instead of specifying the transport name as a string (eg. 'SMTP'), use transport object constructors.

This is the old way (does not work in 1.0) of creating a transporter object:

var transporter = nodemailer.createTransport('SMTP', opts);  

Now use this:

var tranport = require('transport-plugin-name');  
var transporter = nodemailer.createTransport(transport(opts));  

or for the bundled SMTP transport use:

var transporter = nodemailer.createTransport(opts);  

SMTP

SMTP support is divided into three plugins

  • nodemailer-direct-transport sends messages one by one (new connection for every message) directly to the recipients MX. Used automatically if no configuration is provided to createTransport()
var transporter = nodemailer.createTransport(); // <- zero conf  
  • nodemailer-smtp-transport sends messages one by one (new connection for every message) to a specified SMTP gateway. Bundled with Nodemailer so you do not have to install it separately to use it
  • nodemailer-smtp-pool creates a pool of connections against the specified SMTP gateway and sends messages using available connections in the pool. This used to be the default handler for the 'SMTP' transport in Nodemailer 0.x but in 1.0 it is an optional add on and the bundled SMTP transport does not use pooling anymore. If you send only occasional emails, then the pooling gives no advantage and might cause some issues with long idling connections. If you send a lot of emails, then you should definitely consider using pooling.

SES

You can find SES support from nodemailer-ses-transport

sendmail

You can find Sendmail support from nodemailer-sendmail-transport

pickup

You can find Pickup support from nodemailer-pickup-transport

UPDATE

There was a mixup with nodemailer-smtp-connection secure option. It used to be secureConnection in the old Nodemailer and somehow the old option name slipped through in some parts of the new stack. This is now fixed (Nodemailer v1.0.2 and nodemailer-smtp-transport v1.0.11), so use secure as stated in the docs.


comments powered by Disqus