nodemailer 1.7.0 → 1.11.0

package/.npmignore

@@ -1,4 +1,6 @@
 .travis.yml
+.jshintrc
 assets
 examples
-test
+test
+Gruntfile.js

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## v1.11.0 2015-12-28
+
+Allow connection url based SMTP configurations
+
+## v1.10.0 2015-11-13
+
+Added `defaults` argument for `createTransport` to predefine commonn values (eg. `from` address)
+
+## v1.9.0 2015-11-09
+
+Returns a Promise for `sendMail` if callback is not defined
+
+## v1.8.0 2015-10-08
+
+Added priority option (high, normal, low) for setting Importance header
+
 ## v1.7.0 2015-10-06
 
 Replaced hyperquest with needle. Fixes issues with compressed data and redirects

package/README.md

@@ -6,13 +6,7 @@ Send e-mails from Node.js – easy as cake!
 [![Build Status](https://secure.travis-ci.org/andris9/Nodemailer.svg)](http://travis-ci.org/andris9/Nodemailer)
 <a href="http://badge.fury.io/js/nodemailer"><img src="https://badge.fury.io/js/nodemailer.svg" alt="NPM version" height="18"></a>
 
-## 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](https://github.com/andris9/Nodemailer/blob/0.7/README.md).
-
-### Migration guide
-
-See the migration guide from 0.7 to 1.0 [in the 1.0 release blog post](http://www.andrisreinman.com/nodemailer-v1-0/#migrationguide).
+> **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.7 [here](https://github.com/andris9/Nodemailer/blob/0.7/README.md).
 
 ## Notes and information
 
@@ -41,14 +35,8 @@ This is a complete example to send an e-mail with plaintext and HTML body
 ```javascript
 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'
-    }
-});
+// create reusable transporter object using the default SMTP transport
+var transporter = nodemailer.createTransport('smtps://user%40gmail.com:pass@smtp.gmail.com');
 
 // NB! No need to recreate the transporter object. You can use
 // the same transporter object for all e-mails
@@ -72,6 +60,8 @@ transporter.sendMail(mailOptions, function(error, info){
 });
 ```
 
+You may need to ["Allow Less Secure Apps"](https://www.google.com/settings/security/lesssecureapps) in your gmail account (it's all the way at the bottom). You also may need to ["Allow access to your Google account"](https://accounts.google.com/DisplayUnlockCaptcha)
+
 See [nodemailer-smtp-transport](https://github.com/andris9/nodemailer-smtp-transport#usage) for SMTP configuration options and [nodemailer-wellknown](https://github.com/andris9/nodemailer-wellknown#supported-services) 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](#available-transports).
@@ -85,13 +75,14 @@ Install with npm
 To send e-mails you need a transporter object
 
 ```javascript
-var transporter = nodemailer.createTransport(transport)
+var transporter = 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 set [nodemailer-direct-transport](https://github.com/andris9/nodemailer-direct-transport) transport is used. If it is a regular object [nodemailer-smtp-transport](https://github.com/andris9/nodemailer-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.
 
@@ -126,9 +117,14 @@ var transporter = nodemailer.createTransport({
         user: 'sender@gmail.com',
         pass: 'password'
     }
+}, {
+    // default values for sendMail method
+    from: 'sender@address',
+    headers: {
+        'My-Awesome-Header': '123'
+    }
 });
 transporter.sendMail({
-    from: 'sender@address',
     to: 'receiver@address',
     subject: 'hello',
     text: 'hello world!'
@@ -187,6 +183,7 @@ transporter.sendMail({
   * **[nodemailer-html-to-text](https://github.com/andris9/nodemailer-html-to-text)** to auto generate plaintext content from html
   * **[nodemailer-express-handlebars](https://github.com/yads/nodemailer-express-handlebars)** to auto generate html emails from handlebars/mustache templates
   * **[nodemailer-plugin-inline-base64](https://github.com/mixmaxhq/nodemailer-plugin-inline-base64)** to convert base64 images to attachments
+  * **[nodemailer-hashcash](https://github.com/andris9/nodemailer-hashcash)** to generate [hashcash](http://www.hashcash.org/) headers
   * *add yours* (see plugin api documentation [here](#plugin-api))
 
 ## Sending mail
@@ -194,13 +191,13 @@ transporter.sendMail({
 Once you have a transporter object you can send mail
 
 ```javascript
-transporter.sendMail(data, callback)
+transporter.sendMail(data[, callback])
 ```
 
 Where
 
   * **data** defines the mail content (see [e-mail message fields](#e-mail-message-fields) below)
-  * **callback** is an optional callback function to run once the message is delivered or it failed.
+  * **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 transports *should* return the final Message-Id value used with this property
@@ -212,6 +209,8 @@ Where
 
 > If the message includes several recipients then the message is considered sent if at least one recipient is accepted
 
+If `callback` 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.
+
 ### E-mail message fields
 
 The following are the possible fields of an e-mail message:
@@ -228,6 +227,7 @@ The following are the possible fields of an e-mail message:
   - **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  (see [below](#attachments) for details)
   - **alternatives** - An array of alternative text contents (in addition to text and html parts)  (see [below](#alternatives) for details)
@@ -251,6 +251,9 @@ Attachment object consists of the following properties:
   * **contentType** - optional content type for the attachment, if not set will be derived from the `filename` 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.
 
 ```javascript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodemailer",
-  "version": "1.7.0",
+  "version": "1.11.0",
   "description": "Easy as cake e-mail sending from your Node.js applications",
   "main": "src/nodemailer.js",
   "scripts": {
@@ -26,23 +26,23 @@
   },
   "homepage": "http://www.nodemailer.com",
   "devDependencies": {
-    "chai": "^3.3.0",
+    "chai": "^3.4.1",
     "grunt": "^0.4.5",
     "grunt-contrib-jshint": "^0.11.3",
     "grunt-mocha-test": "^0.12.7",
-    "mocha": "^2.3.3",
+    "mocha": "^2.3.4",
     "nodemailer-dkim": "^1.0.3",
     "nodemailer-markdown": "^1.0.0",
     "nodemailer-stub-transport": "^1.0.0",
-    "sinon": "^1.17.1",
-    "smtp-server": "^1.6.0"
+    "sinon": "^1.17.2",
+    "smtp-server": "^1.7.1"
   },
   "dependencies": {
     "libmime": "^1.2.0",
-    "mailcomposer": "^2.0.0",
-    "needle": "^0.10.0",
-    "nodemailer-direct-transport": "^1.0.2",
-    "nodemailer-smtp-transport": "^1.0.3"
+    "mailcomposer": "^2.1.0",
+    "needle": "^0.11.0",
+    "nodemailer-direct-transport": "^1.1.0",
+    "nodemailer-smtp-transport": "^1.1.0"
   },
   "engines": {
     "node": ">=0.10.0"

package/src/nodemailer.js

@@ -11,16 +11,19 @@ var needle = require('needle');
 var PassThrough = require('stream').PassThrough;
 
 // Export createTransport method
-module.exports.createTransport = function(transporter) {
+module.exports.createTransport = function (transporter, defaults) {
     transporter = transporter || directTransport({
         debug: true
     });
 
-    if (typeof transporter === 'object' && typeof transporter.send !== 'function') {
+    if (
+        (typeof transporter === 'object' && typeof transporter.send !== 'function') ||
+        (typeof transporter === 'string' && /^smtps?:/i.test(transporter))
+    ) {
         transporter = smtpTransport(transporter);
     }
 
-    return new Nodemailer(transporter);
+    return new Nodemailer(transporter, defaults);
 };
 
 /**
@@ -29,9 +32,11 @@ module.exports.createTransport = function(transporter) {
  * @constructor
  * @param {Object} transporter Transport object instance to pass the mails to
  */
-function Nodemailer(transporter) {
+function Nodemailer(transporter, defaults) {
     EventEmitter.call(this);
 
+    this._defaults = defaults || {};
+
     this._plugins = {
         compile: [],
         stream: []
@@ -46,7 +51,7 @@ function Nodemailer(transporter) {
 }
 util.inherits(Nodemailer, EventEmitter);
 
-Nodemailer.prototype.use = function(step, plugin) {
+Nodemailer.prototype.use = function (step, plugin) {
     step = (step || '').toString();
     if (!this._plugins.hasOwnProperty(step)) {
         this._plugins[step] = [plugin];
@@ -58,7 +63,7 @@ Nodemailer.prototype.use = function(step, plugin) {
 /**
  * Optional close method, passed to the underlying transport object
  */
-Nodemailer.prototype.close = function( /* possible arguments */ ) {
+Nodemailer.prototype.close = function ( /* possible arguments */ ) {
     var args = Array.prototype.slice.call(arguments);
     if (typeof this.transporter.close === 'function') {
         this.transporter.close.apply(this.transporter, args);
@@ -71,10 +76,32 @@ Nodemailer.prototype.close = function( /* possible arguments */ ) {
  * @param {Object} data E-data description
  * @param {Function} callback Callback to run once the sending succeeded or failed
  */
-Nodemailer.prototype.sendMail = function(data, callback) {
+Nodemailer.prototype.sendMail = function (data, callback) {
+    var promise;
+
+    if (!callback && typeof Promise === 'function') {
+        promise = new Promise(function (resolve, reject) {
+            callback = callbackPromise(resolve, reject);
+        });
+    }
+
     data = data || {};
     data.headers = data.headers || {};
-    callback = callback || function() {};
+    callback = callback || function () {};
+
+    // apply defaults
+    Object.keys(this._defaults).forEach(function (key) {
+        if (!(key in data)) {
+            data[key] = this._defaults[key];
+        } else if (key === 'headers') {
+            // headers is a special case. Allow setting individual default headers
+            Object.keys(this._defaults.headers || {}).forEach(function (key) {
+                if (!(key in data.headers)) {
+                    data.headers[key] = this._defaults.headers[key];
+                }
+            }.bind(this));
+        }
+    }.bind(this));
 
     var mail = {
         data: data,
@@ -83,10 +110,10 @@ Nodemailer.prototype.sendMail = function(data, callback) {
     };
 
     if (typeof this.transporter === 'string') {
-        return callback(new Error('Unsupported configuration, downgrade Nodemailer to v0.7.1 or see the migration guide https://github.com/andris9/Nodemailer#migration-guide'));
+        return callback(new Error('Unsupported configuration, downgrade Nodemailer to v0.7.1 to use it'));
     }
 
-    this._processPlugins('compile', mail, function(err) {
+    this._processPlugins('compile', mail, function (err) {
         if (err) {
             return callback(err);
         }
@@ -97,13 +124,32 @@ Nodemailer.prototype.sendMail = function(data, callback) {
             mail.message.setHeader('X-Mailer', mail.data.xMailer || this._getVersionString());
         }
 
-        this._processPlugins('stream', mail, function(err) {
+        if (mail.data.priority) {
+            switch ((mail.data.priority || '').toString().toLowerCase()) {
+                case 'high':
+                    mail.message.setHeader('X-Priority', '1 (Highest)');
+                    mail.message.setHeader('X-MSMail-Priority', 'High');
+                    mail.message.setHeader('Importance', 'High');
+                    break;
+                case 'low':
+                    mail.message.setHeader('X-Priority', '5 (Lowest)');
+                    mail.message.setHeader('X-MSMail-Priority', 'Low');
+                    mail.message.setHeader('Importance', 'Low');
+                    break;
+                default:
+                    // do not add anything, since all messages are 'Normal' by default
+            }
+        }
+
+        this._processPlugins('stream', mail, function (err) {
             if (err) {
                 return callback(err);
             }
             this.transporter.send(mail, callback);
         }.bind(this));
     }.bind(this));
+
+    return promise;
 };
 
 /**
@@ -119,7 +165,15 @@ Nodemailer.prototype.sendMail = function(data, callback) {
  * @param {String|Number} key Property name or an Array index
  * @param {Function} callback Callback function with (err, value)
  */
-Nodemailer.prototype.resolveContent = function(data, key, callback) {
+Nodemailer.prototype.resolveContent = function (data, key, callback) {
+    var promise;
+
+    if (!callback && typeof Promise === 'function') {
+        promise = new Promise(function (resolve, reject) {
+            callback = callbackPromise(resolve, reject);
+        });
+    }
+
     var content = data && data[key] && data[key].content || data[key];
     var contentStream;
     var encoding = (typeof data[key] === 'object' && data[key].encoding || 'utf8')
@@ -133,7 +187,7 @@ Nodemailer.prototype.resolveContent = function(data, key, callback) {
 
     if (typeof content === 'object') {
         if (typeof content.pipe === 'function') {
-            return this._resolveStream(content, function(err, value) {
+            return this._resolveStream(content, function (err, value) {
                 if (err) {
                     return callback(err);
                 }
@@ -149,7 +203,7 @@ Nodemailer.prototype.resolveContent = function(data, key, callback) {
                 parse_response: false,
                 compressed: true,
                 follow_max: 5
-            }).on('end', function(err) {
+            }).on('end', function (err) {
                 if (err) {
                     contentStream.emit('error', err);
                 }
@@ -174,7 +228,9 @@ Nodemailer.prototype.resolveContent = function(data, key, callback) {
     }
 
     // default action, return as is
-    callback(null, content);
+    setImmediate(callback.bind(null, null, content));
+
+    return promise;
 };
 
 /**
@@ -183,12 +239,12 @@ Nodemailer.prototype.resolveContent = function(data, key, callback) {
  * @param {Object} stream Readable stream
  * @param {Function} callback Callback function with (err, value)
  */
-Nodemailer.prototype._resolveStream = function(stream, callback) {
+Nodemailer.prototype._resolveStream = function (stream, callback) {
     var responded = false;
     var chunks = [];
     var chunklen = 0;
 
-    stream.on('error', function(err) {
+    stream.on('error', function (err) {
         if (responded) {
             return;
         }
@@ -197,14 +253,14 @@ Nodemailer.prototype._resolveStream = function(stream, callback) {
         callback(err);
     });
 
-    stream.on('data', function(chunk) {
+    stream.on('data', function (chunk) {
         if (chunk && chunk.length) {
             chunks.push(chunk);
             chunklen += chunk.length;
         }
     });
 
-    stream.on('end', function() {
+    stream.on('end', function () {
         if (responded) {
             return;
         }
@@ -221,7 +277,7 @@ Nodemailer.prototype._resolveStream = function(stream, callback) {
     });
 };
 
-Nodemailer.prototype._getVersionString = function() {
+Nodemailer.prototype._getVersionString = function () {
     return util.format(
         '%s (%s; +%s; %s/%s)',
         packageData.name,
@@ -232,7 +288,7 @@ Nodemailer.prototype._getVersionString = function() {
     );
 };
 
-Nodemailer.prototype._processPlugins = function(step, mail, callback) {
+Nodemailer.prototype._processPlugins = function (step, mail, callback) {
     step = (step || '').toString();
 
     if (!this._plugins.hasOwnProperty(step) || !this._plugins[step].length) {
@@ -241,12 +297,12 @@ Nodemailer.prototype._processPlugins = function(step, mail, callback) {
 
     var plugins = Array.prototype.slice.call(this._plugins[step]);
 
-    var processPlugins = function() {
+    var processPlugins = function () {
         if (!plugins.length) {
             return callback(null);
         }
         var plugin = plugins.shift();
-        plugin(mail, function(err) {
+        plugin(mail, function (err) {
             if (err) {
                 return callback(err);
             }
@@ -255,4 +311,23 @@ Nodemailer.prototype._processPlugins = function(step, mail, callback) {
     }.bind(this);
 
     processPlugins();
-};
+};
+
+/**
+ * Wrapper for creating a callback than either resolves or rejects a promise
+ * based on input
+ *
+ * @param {Function} resolve Function to run if callback is called
+ * @param {Function} reject Function to run if callback ends with an error
+ */
+function callbackPromise(resolve, reject) {
+    return function () {
+        var args = Array.prototype.slice.call(arguments);
+        var err = args.shift();
+        if (err) {
+            reject(err);
+        } else {
+            resolve.apply(null, args);
+        }
+    };
+}

package/.jshintrc

@@ -1,20 +0,0 @@
-{
-    "indent": 4,
-    "node": true,
-    "globalstrict": true,
-    "evil": true,
-    "unused": true,
-    "undef": true,
-    "newcap": true,
-    "esnext": true,
-    "curly": true,
-    "eqeqeq": true,
-    "expr": true,
-
-    "predef": [
-        "describe",
-        "it",
-        "beforeEach",
-        "afterEach"
-    ]
-}

package/Gruntfile.js

@@ -1,30 +0,0 @@
-'use strict';
-
-module.exports = function(grunt) {
-
-    // Project configuration.
-    grunt.initConfig({
-        jshint: {
-            all: ['src/*.js', 'test/*.js', 'examples/*.js', 'Gruntfile.js'],
-            options: {
-                jshintrc: '.jshintrc'
-            }
-        },
-
-        mochaTest: {
-            all: {
-                options: {
-                    reporter: 'spec'
-                },
-                src: ['test/*-test.js']
-            }
-        }
-    });
-
-    // Load the plugin(s)
-    grunt.loadNpmTasks('grunt-contrib-jshint');
-    grunt.loadNpmTasks('grunt-mocha-test');
-
-    // Tasks
-    grunt.registerTask('default', ['jshint', 'mochaTest']);
-};