/grunt-nodemailer

Grunt wrapper for Nodemailer

Primary LanguageJavaScriptMIT LicenseMIT

grunt-nodemailer

Grunt wrapper for Nodemailer

❗ ❗MAINTAINERS WANTED: I'm no longer maintaining this project. Feel free to drop me a line if you're interested in keeping up the development ❗ ❗

Getting Started

This plugin is compatible with Grunt 1.x but requires Grunt >=0.4.2

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-nodemailer --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-nodemailer');

The "nodemailer" task

Overview

In your project's Gruntfile, add a section named nodemailer to the data object passed into grunt.initConfig().

grunt.initConfig({
  nodemailer: {
    options: {
      // Task-specific options go here.
    },
    your_target: {
      // Target-specific file lists and/or options go here.
    },
  },
})

Options

options.transport

Type: Object Default value: null

A nodemailer transform object. See the official documentation for details.

Note: if not set will default to sendmail transport.

options.message

Type: Object Default value: {}

E-mail message configuration. See Nodemailer documentation for available options.

options.recipients

Type: Array Default value: []

A collection of recipients. Every item should have 2 properties:

  • name: Name of the recipient
  • email: E-mail address of the recipient

Note: Recipients specified here will be appended to those set in options.message.to.

options.from DEPRECATED since v0.2

See options.message for details.

options.subject DEPRECATED since v0.2

See options.message for details.

options.html DEPRECATED since v0.2

See options.message for details.

options.text DEPRECATED since v0.2

See options.message for details.

Using external files

BREAKING CHANGES: before v0.2 you had to provide 2 source files in order to pass HTML and text body message. Since v0.2 text files are automatically discovered. Keep reading for details.

Instead of providing text and html message options you may use external files by setting a src property on the sub-task. All file extensions except .html will be used as text option for the email.

If HTML files are provided, the task will look for .txt files with same filename to be used as text fallbacks.

Example:

nodemailer: {
  test: {
    options: { /* ... transport, message, etc ...*/},
    src: ['email-body.html']
  }
}

//Will use email-body.html for HTML email body,
//optionally using email-body.txt (if found) as text fallback

If multiple files are passed in, a message for each one will be delivered.

nodemailer: {
  test: {
    options: { /* ... transport, message, etc ...*/},
    src: ['email-body.html', 'email-body2.html']
  }
}

//Will send 2 messages

Note: If HTML files include title tag it'll be used as the message subject.

CLI Options

--fileSrc

Type: String Default value: null

Overrides src files set in the task configuration.

Usage Examples

E-mail delivery with Gmail SMTP server

This configurations uses Gmail's SMTP service as transport.

By running the nodemailer:external task HTML body will be overridden.

var nodemailer = require('nodemailer');

var gmailTransport = nodemailer.createTransport('smtps://john.doe%40gmail.com:password@smtp.gmail.com');

grunt.initConfig({
  nodemailer: {

    options: {
      transport: gmailTransport,
      message: {
        subject: 'A test e-mail',
        text: 'Plain text message',
        html: '<body><h1>HTML custom message</h1></body>',
      },
      recipients: [
        {
          email: 'jane.doe@gmail.com',
          name: 'Jane Doe'
        }
      ]
    },

    inline: { /* use above options*/ },

    external: {
      src: ['email-body.html']
    }
  }
});

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Release History

1.1.0 Updated to Nodemailer 2.x and Grunt 1.x ready

1.0.0 Updated to Nodemail 1+ APIs, added support for every filetype as external source (thanks to @wardpeet)

0.3.0 Added grunt cli option to override file src (thanks to @posabsolute)

0.2.1 Display error message instead of error name (fixes issue #3 thanks to @aszmyd)

0.2.0 - Task allows for multiple external sources to better comply to Grunt's file APIs. As of this version, you may set any supported Nodemailer message's option onto options.message. Added some tests.

0.1.2 - Replaced deprecated reference to grunt.util._ with lodash npm module

0.1.1 - Bugfix

0.1.0 - Initial release