Package Exports

horseshoe

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (horseshoe) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

horseshoe

horseshoe is a mailer module for node.js. It provides a wrapper around nodemailer used for sending email using handlebars templates.

horseshoe is designed for a very specific use case. We use it at ENOISE to send out system emails using SMTP and Amazon SES. This emails are predesigned using handlebars templates and then rendered and sent using this module.

horseshoe renders templates using the data specified in the message object:

var message = {
  to: 'someone@somewhere.com',
  template: 'users-signup',
  data: { user: { firstname: 'Lupo' } }
};

horseshoe will search the templates path for files with either a .txt or .html extension (users-signup.txt and users-signup.html in this case) and render them using handlebars to create the email body.

horseshoe exports a single function. You invoke this function to get a mailer object that you can the use to either send a single message with mailer.send() or create a writable stream with mailer.createStream() to send multiple messages using the streaming interface.

horseshoe will retry to send individual emails if they fail (up to 3 times).

THIS MODULE IS STILL WORK IN PROGRESS

Installation

npm install horseshoe

To install globally and have the command line tool placed in your PATH use:

npm install horseshoe -g

Usage

Let's assume that your script is myscript.js and you have a directory called mail_templates in the same location containing a template called users-signup.txt (relative to script: mail_templates/users-signup.txt).

In myscript.js:

var
  mailer = require('horseshoe')('Sendmail', { tmplpath: __dirname + '/mail_templates/' }),
  message = {
    to: 'someone@somewhere.com',
    template: 'users-signup',
    data: { user: { firstname: 'Lupo' } }
  };

mailer.send(message, function (error, response) {
  if (error) {
    // handle error
  }
});

The mail_templates/users-signup.txt template:

This is a test subject

Hey {{user.firstname}},

I hope you like my test email...

Bye!

Streaming interface

Example:

var
  stream = require('horseshoe')('Sendmail').createStream(),
  messages = [
    { to: 'someone@somewhere.com', template: 'signup', data: { name: 'Lupo' } },
    { to: 'someone.else@somewhere.com', template: 'signup', data: { name: 'Someone' } }
  ];

  stream.on('error', function (error) { /*handle error*/ });
  stream.on('data', function (response) { /*info about message sent */ });
  stream.on('end', function () { /*done sending*/ });

  messages.forEach(function (message) {
    stream.write(message);
  });

  stream.end();

Supported transports

horseshoe passes its options to nodemailer and so you can use all transports supported by nodemailer.

For more info see nodemailer's README.

Sendmail example

var mailer = require('horseshoe')('Sendmail', {
  path: "/usr/local/bin/sendmail",
  args: ["-f foo@blurdybloop.com"]
});

SMTP

var mailer = require('horseshoe')('SMTP', {
  sender: 'Someone <someone@somewhere.com>',
  host: 'mail.somewhere.com',
  port: 587,
  auth: {
    user: 'someone@somewhere.com',
    pass: 'somepassowrd'
  }
});

Amazon SES

var mailer = require('horseshoe')('SES', {
  AWSAccessKeyID: "YOUR-AMAZON-SES-KEY",
  AWSSecretKey: "YOUR-AMAZON-SES-SECRET"
});

Postmark

Note that you need to enable SMTP on https://postmarkapp.com/ and then use our API key both as username and password.

More info here: http://developer.postmarkapp.com/developer-smtp.html

var mailer = require('horseshoe')('SMTP', {
  service: 'Postmark',
  auth: {
    user: "YOUR-POSTMARK-API-KEY",
    pass: "YOUR-POSTMARK-API-KEY"
  }
});

Command line tool

The command line has its own help file. Just run:

horseshoe

horseshoe --help