actionhero-nodemailer-plugin

Index

• What
  • Feature List
• How
  • Installing
  • Configuration
  • Mail Templates
  • Usage
• API Methods
• TODO

What

Mail sending plugin for actionhero API Server using nodemailer. Provides api methods and task runner to configure and send Mail from within an actionhero API Server. It's also integrated with mail template capability from email-templates package.

Feature List

• Various supported mail transport by nodemailer.
• Mail template capability from email-templates package, using ejs / jade / swig / handlebars.
• Built in task for sending mail.
• Easy configuration.
• Supports Promises/A+ and classic callback style

How

Installing

*NOTE! First, make sure you have a plugins directory inside your actionhero's config directory. It's considered a good practice to group configuration files from ah-plugin package and i will do so for any plugin i release. The postinstall script will copy the config file to the directory and will throw error if there is no plugins directory. I will fix this in the future.

After that, in your actionhero project, install the plugin from NPM.

npm install ah-nodemailer-plugin --save

Configuration

After installation is finished, there will be a configuration file copied to your /config/plugins folder named mailer.js. Below is the default configuration file content, modify it to meet your needs.

exports["default"] = {
  mailer: function(api) {
    return {

      /*
      Type of transport to use.
      See [nodemailer](http://www.nodemailer.com/docs/transports).
      If set to ``stdout``, no email will be sent,
      instead it will be piped to stdout.
       */
      transport: "stdout",

      /*
      This is an example of options to use in transport creation, using SMTP.
      For other nodemailer supported transport, please see nodemailer's site.
       */
      options: {

        /*
        an optional well known service identifier ("Gmail", "Hotmail" etc.,
        see Well known Services for a list of supported services)
        to auto-configure host, port and secure connection settings
         */
        service: "Gmail",
        host: "smtp.example.com",
        port: 25,
        secureConnection: false,
        name: "example-mailer",
        auth: {
          user: "[email protected]",
          pass: "some_password"
        }
      },

      /*
      Default options when sending email.
      Define other fields here if you wish.
       */
      mailOptions: {
        from: "[email protected]"
      },

      /*
      Email templates directory.
      Defaults to root `templates` directory.
       */
      templates: "" + __dirname + "/../../templates"
    };
  }
};

You can see a list of supported transports in nodemailer site

Mail Templates

This plugin supports, or rather required for now, to use mail template. By default you have to create a folder called templates in your root actionhero project. In there, place folders of templates with template files named html.{{template engine}}, text.{{template engine}}, and/or, style.{{CSS pre-processor}}. See node-email-templates for more detailed explanation.

your-actionhero-project
├── actions
├── config
├── ...
├── templates
    ├── welcome
    |   ├── html.ejs
    |   ├── text.ejs
    |   ├── style.less
    |
    ├── resetPassword
    |   ├── html.ejs
    |   ├── text.ejs
    |   ├── style.less
    |
    ├── etc.etc.

The location of templates directory can be configured in mailer.js configuration file above, relative to the config file's location.

Usage

The api is exposed in api.Mailer object. To send mail, you can use the api.Mailer.send(options, callback) method directly or better yet use the built in task named sendMail so the request is not held by mail sending process.

// Using api.Mailer.send directly
options = {
  mail: {
    to: '[email protected]',
    subject: 'Hello Nodemailer From Actionhero!'
  },
  locals: {
    foo: 'bar',
    baz: 'derp'
  },
  template: 'welcome'
};

api.Mailer.send(options)
.then(function(response) {
  api.log('Mail sent successfully!');
  // do something else
}).catch(function(error) {
  api.log('Something bad happened', 'crit', error.message);
});

// or using classic callback
api.Mailer.send(options, function(error, response) {
  if(error)
    api.log('Something bad happened', 'crit', error.message);
  else {
    api.log('Mail sent successfully!');
    // do something else
  }
});

// Using the built in task runner
api.tasks.enqueue('sendMail', options, 'default', function(error, done) {
  //done
})

API Methods

api.Mailer.send(options, callback)

Send mail with nodemailer plugin. Returns a promise object which will be resolved with mail sending response object, or rejected if there is any error.

• options (required) hash of option to send the email, consists of this following fields:
  • mail The email message field, as described here. You can provide default values in mailer.js config under mailOptions field.
  • locals The data to provide to the template file.
  • template The template name to use.
• callback (optional) Function to call after the mail sending process is finished. Will be called with 2 arguments, error and response.

api.tasks.enqueue('sendMail', options, queueName, callback)

Send mail through a task named sendMail. The options argument is the same as above.

TODO

• Provide test.
• Provide implementation sample.