jamoose

Preprocessing and Sending HTML Emails in Node.js

Goals

Send HTML Emails
Use preprocessors like Jade and Sass to write them
Only care about the template and its data at time of sending

Getting Started

This plugin 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 jamoose --save

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

require('jamoose')(grunt);

If you can figure out how I can use loadNpmTasks, please open a pull request

You can require it in your application like so:

var jamoose = require('jamoose'),
    Mailer = new jamoose({});

The Grunt task

Overview

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

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

Options

options.jade

Type: Object Default value: {}

Same as Jade API options

_NB: options.jade.filename defaults to the current file's path

options.juice

Type: Object Default value: { url: 'file://' + process.cwd() + '/' }

Same as Juice options

Important: End your url with a trailing slash

Usage Example

grunt.initConfig({
  jamoose: {
    default_options: {
      files: [
        {
          expand: true,
          flatten: false,
          cwd: 'test/fixtures',
          src: '**/*.jade',
          dest: 'tmp',
          ext: '.html'
        }
      ]
    }
  }
});

Using in your application

See the examples for detailed, working code.

Create your email template using Jade. Use Jade variables for anything you want replaced at build time (think cross-app vars like domains and dates). Use Mustache variables for anything you want inserted at send time (think user-specific details like name or address)

//- welcome.jade
html
  head
    link(rel="stylesheet", href="path/to/email.css")
  body
    table
      tr
        td
          h1 Welcome {{name}}

      tr
        td
          a(href=domain + '/privacy') Privacy Policy

// email.sass
h1
  font-size: 30px
  color: #333

Build your templates with Grunt

$ grunt sass jamoose

You now will have an HTML file with inlined CSS* and Mustache variables still in tact.

Thanks to LearnBoost/juice

<html>
  <body>
    <table>
      <tr>
        <td>
          <h1 style="font-size:30px;color:#333">Welcome {{name}}</h1>
        </td>
      </tr>
      <tr>
        <td>
          <a href="http://your.domain.from.grunt/privacy">Privacy Policy</a>
        </td>
      </tr>
    </table>
  </body>
</html>

Send an email in your app

var jamoose = require('jamoose'),
    mailer = new jamoose({
      tplPath: 'path/to/templates/from/grunt/',
      fromEmail: 'sender@edc.ba'
    });

mailer.send(
  'test@abc.de', // to
  'Welcome!', // subject
  'welcome', // template
  { // data
    name: 'John Smith'
  },
  function(err) { // callback
    if (err) { console.log(err); }
  }
);

"Welcome John Smith" will be sent to "test@abc.de" from "sender@edc.ba" with the subject "Welcome!"

Email Providers

Currently supporting:

Please submit a pull request to add more service providers.

Set the environment variables for the provider of your choice and it will be used automatically.

SendGrid

SendGrid's node library is used under the hood. Required environment variables:

SENDGRID_USER - API user (usually email address)
SENDGRID_KEY - API key (usually your password)

Mandrill

Mandrill's node library is used under the hood. Required environment variable:

MANDRILL - API key (create one from your settings page)

Using in development

If process.env.NODE_ENV is set to development, HTML files will be written to a temporary file when you send. The path is console.log for you to inspect. If you'd like to actually send an email during development or locally, set process.env.NODE_ENV to something besides development.

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.

Testing

Tests are written with nodeunit and can be run with npm test

Release History

v2.0.0 - Drop support for Node v0.8 v1.0.0 - Add Mandrill support

maxbeatty/jamoose