Migration from 1.x to 2.x

In most cases nothing needs to be changed to upgrade from Nodemailer 1.x to 2.x, as in most cases 2.x should be backwards compatible with 1.x. There are some differences though which could be checked for.

Logging

Nodemailer 1.x emitted 'log' events with structured log values that could be handled this:

var transporter = nodemailer.createTransport(...);
transporter.on('log', function(log){
     console.log('%s: %s', log.type, log.message);
});

Nodemailer 2.x uses bunyan compatible logger instances (compatible meaning that the logger object should have debug, info and error methods, the logger does not need to be an actual bunyan interface). If you set the logger as true then log messages are printed to console.

var bunyan = require('bunyan');
var transporter = nodemailer.createTransport({
    service: 'gmail',
    auth: ...,
    // pass logs to the bunyan instance
    logger: bunyan.createLogger({name: 'nodemailer'})
});

or

var transporter = nodemailer.createTransport({
    service: 'gmail',
    auth: ...,
    // pass logs to console
    logger: true
});

If you continue to listen for 'log' events then nothing breaks, you just don’t receive the log messages anymore.

SMTP configuration

Even though you can still keep using the external plugin approach then all SMTP related plugins are now baked in and do not need external loading.

SMTP pool

Previously it was needed to load nodemailer-smtp-pool module to use pooling with SMTP. Now you need to set pool option to true in the SMTP config and Nodemailer automatically switches over to pooling.

var transporter = nodemailer.createTransport({
    service: 'gmail',
    auth: ...,
    // use pooling
    pool: true
});

Direct transport

Previously it was needed to load nodemailer-direct-transport module to send messages directly to recipients MX server. Now you need to set direct option to true in the SMTP config and Nodemailer automatically switches over to direct sending.

var transporter = nodemailer.createTransport({
    // if you do not provide the reverse resolved hostname
    // then the recipients server might reject the connection
    name: 'my-server-hostname',
    // use direct sending
    direct: true
});

Connection URL support

Another distinction between Nodemailer 1.x and 2.x is that you can use connection URLs for configuring SMTP. Use smtp: protocol for non-encrypted or STARTTLS connections (port 25 or 587), smtps: for encrypted connection (port 465), direct: for direct sending (in this case you do not need to set hostname etc.). Use url arguments for additional config.

var smtpConfig = 'smtp://user%40gmail.com:[email protected]:587';
var smtpsConfig = 'smtps://user%40gmail.com:[email protected]';
var poolConfig = 'smtps://user%40gmail.com:[email protected]/?pool=true';
var directConfig = 'direct:?name=hostname';

var transporter = nodemailer.createTransport(smtpConfig);