sails-hook-email-multi-transport

Email hook for Sails JS, using Nodemailer, which allows for multiple Nodemailer transports for sending different types of email though different ways.

Note: This requires Sails v0.10.6+.

Installation

npm install sails-hook-email-multi-transport

Usage

sails.hooks.email.send(template, data, options, cb)

Parameter | Type | Details -------------- | ------------------- |:--------------------------------- template | ((string)) | Relative path from templateDir (see "Configuration" below) to a folder containing email templates. data | ((object)) | Data to use to replace template tokens options | ((object)) | Email sending options (see Nodemailer docs) cb | ((function)) | Callback to be run after the email sends (or if an error occurs).

Configuration

By default, configuration lives in sails.config.email. The configuration key (email) can be changed by setting sails.config.hooks['sails-hook-email-multi-transport'].configKey. The configuration is a single configuration object or an array of objects that look like this:

Parameter | Type | Details -------------- | ------------------- |:--------------------------------- transporters | ((array)) | An array of transporter objects (described below) templateDir | ((string)) | Path to view templates relative to sails.config.appPath (defaults to views/emailTemplates) from | ((string)) | Default from email address alwaysSendTo | ((string)) | If set, all emails will be sent to this address regardless of the to option specified. Good for testing live emails without worrying about accidentally spamming people. testMode | ((boolean)) | Flag indicating whether the hook is in "test mode" globally for all transports. In test mode, email options and contents are written to a .tmp/email-TRANSPORT.txt file instead of being actually sent. Defaults to true. defaultTransporter | ((string)) | The name of the transporter to use if none is specified. useDefaultTransportIfMissing | ((boolean)) | Whether to fall back to the default transport if the specified name does not exist. Note that this generates a warning on the console.

Additionally, if the transporters configuration option does not exist, a new "default" transporter is created by reading the transporter options listed below directly from the config object. This allows backwards compatibility with sails-hook-email.

Transporter Object definition

Parameter | Type | Details -------------- | ------------------- |:--------------------------------- name | ((string)) | The name of this transporter to reference it later service | ((string)) | A "well-known service" that Nodemailer knows how to communicate with (see this list of services) auth | ((object)) | Authentication object as {user:"...", pass:"..."} transporter | ((object)) | Custom transporter passed directly to nodemailer.createTransport (overrides service/auth) (see Other Transports) testMode | ((boolean)) | Flag indicating whether the hook is in "test mode". In test mode, email options and contents are written to a .tmp/email-TRANSPORT.txt file instead of being actually sent. Defaults to undefined which inhertis from the global testMode setting described above.

Example Configuration

// [your-sails-app]/config/email.js
module.exports.email = {
  transporters: [
    {
      name: 'MyGmail',
      isDefault: true,
      service: 'Gmail',
      auth: {user: '[email protected]', pass: 'emailpassword'},
      testMode: true
    }
  ]
};

Templates

Templates are generated using your configured Sails View Engine, allowing for multiple template engines and layouts. If Sails Views are disabled, will fallback to EJS templates. To define a new email template, create a new folder with the template name inside your templateDir directory, and add an html.ejs file inside the folder (substituting .ejs for your template engine). You may also add an optional text.ejs file; if none is provided, Nodemailer will attempt to create a text version of the email based on the html version.

Example of templates

Given the following html.ejs file contained in the folder views/emailTemplates/testEmail:

<p>Dear <%=recipientName%>,</p>
<br/>
<p><em>Thank you</em> for being a friend.</p>
<p>Love,<br/><%=senderName%></p>

executing the following command (after configuring for your email service and turning off test mode) :

sails.hooks.email.send(
  "testEmail",
  {
    recipientName: "Joe",
    senderName: "Sue"
  },
  {
    to: "[email protected]",
    subject: "Hi there",
    transport: "MyGmail"
  },
  function(err) {console.log(err || "It worked!");}
)

will result in the following email being sent to [email protected]

Dear Joe,

Thank you for being a friend.

Love,

Sue

with an error being printed to the console if one occurred, otherwise "It worked!".