node-email-templates

Node.js module for rendering beautiful emails with your template engine and CSS pre-processor of choice coupled with email-friendly inline CSS using juice.

View documentation here .

Follow @niftylettuce on Twitter for updates.

Like this module? Check out express-cdn!

The Rebel's Guide to Email Marketing	Modern HTML Email	Email Marketing By the Numbers

Index

• Email Templates
• Installation
• Quick Start
• EJS Custom Tags
• Examples
  • Basic
  • Nodemailer
  • Postmark
• Lazyweb Requests
• Changelog
• Contributors
• License

Email Templates

For professional and customizable email templates, please visit .

Supported Template Engines

• ejs
• jade
• swig
• handlebars

Supported CSS Pre-processors

• less
• sass
• stylus
• styl

Installation

Unix/OS X

npm install email-templates

Windows

npm install email-templates-windows

Quick Start

1. Install the module for your respective project npm install email-templates.
2. Create a folder called templates inside your root directory (or elsewhere).
3. For each of your templates, respectively name and create a folder inside the templates folder.
4. Add the following files inside the template's folder:
   • html.{{template engine}} - See supported template engines (required)
   • text.{{template engine}} - See supported template engines (optional)
   • style.{{CSS pre-processor}} - See supported CSS pre-processors (optional)
5. You may use the include directive from ejs (for example, to include a common header or footer). See the /examples folder for details.
6. Utilize one of the examples below for your respective email module and start sending beautiful emails!

Templating Language Options (e.g. EJS Custom Tags)

Want to use different opening and closing tags instead of the EJS's default <% and %>?.

...
emailTemplates(templatesDir, { open: '{{', close: '}}' }, function(err, template) {
...

NOTE: You can also pass other options from EJS's documentation.

Examples

Basic

Render a template for a single email or render multiple (having only loaded the template once).

var path           = require('path')
  , templatesDir   = path.join(__dirname, 'templates')
  , emailTemplates = require('email-templates');

emailTemplates(templatesDir, function(err, template) {

  // Render a single email with one template
  var locals = { pasta: 'Spaghetti' };
  template('pasta-dinner', locals, function(err, html, text) {
    // ...
  });

  // Render multiple emails with one template
  var locals = [
    { pasta: 'Spaghetti' },
    { pasta: 'Rigatoni' }
  ];
  var Render = function(locals) {
    this.locals = locals;
    this.send = function(err, html, text) {
      // ...
    };
    this.batch = function(batch) {
      batch(this.locals, this.send);
    };
  };
  template('pasta-dinner', true, function(err, batch) {
    for(var user in users) {
      var render = new Render(users[user]);
      render.batch(batch);
    }
  });

});

Nodemailer

var path           = require('path')
  , templatesDir   = path.resolve(__dirname, '..', 'templates')
  , emailTemplates = require('email-templates')
  , nodemailer     = require('nodemailer');

emailTemplates(templatesDir, function(err, template) {

  if (err) {
    console.log(err);
  } else {

    // ## Send a single email

    // Prepare nodemailer transport object
    var transport = nodemailer.createTransport("SMTP", {
      service: "Gmail",
      auth: {
        user: "some-user@gmail.com",
        pass: "some-password"
      }
    });

    // An example users object with formatted email function
    var locals = {
      email: 'mamma.mia@spaghetti.com',
      name: {
        first: 'Mamma',
        last: 'Mia'
      }
    };

    // Send a single email
    template('newsletter', locals, function(err, html, text) {
      if (err) {
        console.log(err);
      } else {
        transport.sendMail({
          from: 'Spicy Meatball ',
          to: locals.email,
          subject: 'Mangia gli spaghetti con polpette!',
          html: html,
          // generateTextFromHTML: true,
          text: text
        }, function(err, responseStatus) {
          if (err) {
            console.log(err);
          } else {
            console.log(responseStatus.message);
          }
        });
      }
    });


    // ## Send a batch of emails and only load the template once

    // Prepare nodemailer transport object
    var transportBatch = nodemailer.createTransport("SMTP", {
      service: "Gmail",
      auth: {
        user: "some-user@gmail.com",
        pass: "some-password"
      }
    });

    // An example users object
    var users = [
      {
        email: 'pappa.pizza@spaghetti.com',
        name: {
          first: 'Pappa',
          last: 'Pizza'
        }
      },
      {
        email: 'mister.geppetto@spaghetti.com',
        name: {
          first: 'Mister',
          last: 'Geppetto'
        }
      }
    ];

    // Custom function for sending emails outside the loop
    //
    // NOTE:
    //  We need to patch postmark.js module to support the API call
    //  that will let us send a batch of up to 500 messages at once.
    //  (e.g. )
    var Render = function(locals) {
      this.locals = locals;
      this.send = function(err, html, text) {
        if (err) {
          console.log(err);
        } else {
          transportBatch.sendMail({
            from: 'Spicy Meatball ',
            to: locals.email,
            subject: 'Mangia gli spaghetti con polpette!',
            html: html,
            // generateTextFromHTML: true,
            text: text
          }, function(err, responseStatus) {
            if (err) {
              console.log(err);
            } else {
              console.log(responseStatus.message);
            }
          });
        }
      };
      this.batch = function(batch) {
        batch(this.locals, templatesDir, this.send);
      };
    };

    // Load the template and send the emails
    template('newsletter', true, function(err, batch) {
      for(var user in users) {
        var render = new Render(users[user]);
        render.batch(batch);
      }
    });

  }
});

Postmark

This example utilizes Postmark.js.

NOTE: Did you know nodemailer can also be used to send SMTP email through Postmark? See this section of their Readme for more info.

For more message format options, see this section of Postmark's developer documentation section.

var path           = require('path')
  , templatesDir   = path.resolve(__dirname, '..', 'templates')
  , emailTemplates = require('email-templates')
  , postmark       = require('postmark')('your-api-key');

emailTemplates(templatesDir, function(err, template) {

  if (err) {
    console.log(err);
  } else {

    // ## Send a single email

    // An example users object with formatted email function
    var locals = {
      email: 'mamma.mia@spaghetti.com',
      name: {
        first: 'Mamma',
        last: 'Mia'
      }
    };

    // Send a single email
    template('newsletter', locals, function(err, html, text) {
      if (err) {
        console.log(err);
      } else {
        postmark.send({
          From: 'Spicy Meatball ',
          To: locals.email,
          Subject: 'Mangia gli spaghetti con polpette!',
          HtmlBody: html,
          TextBody: text
        }, function(err, response) {
          if (err) {
            console.log(err.status);
            console.log(err.message);
          } else {
            console.log(response);
          }
        });
      }
    });


    // ## Send a batch of emails and only load the template once

    // An example users object
    var users = [
      {
        email: 'pappa.pizza@spaghetti.com',
        name: {
          first: 'Pappa',
          last: 'Pizza'
        }
      },
      {
        email: 'mister.geppetto@spaghetti.com',
        name: {
          first: 'Mister',
          last: 'Geppetto'
        }
      }
    ];

    // Custom function for sending emails outside the loop
    //
    // NOTE:
    //  We need to patch postmark.js module to support the API call
    //  that will let us send a batch of up to 500 messages at once.
    //  (e.g. )
    var Render = function(locals) {
      this.locals = locals;
      this.send = function(err, html, text) {
        if (err) {
          console.log(err);
        } else {
          postmark.send({
            From: 'Spicy Meatball ',
            To: locals.email,
            Subject: 'Mangia gli spaghetti con polpette!',
            HtmlBody: html,
            TextBody: text
          }, function(err, response) {
            if (err) {
              console.log(err.status);
              console.log(err.message);
            } else {
              console.log(response);
            }
          });
        }
      };
      this.batch = function(batch) {
        batch(this.locals, templatesDir, this.send);
      };
    };

    // Load the template and send the emails
    template('newsletter', true, function(err, batch) {
      for(user in users) {
        var render = new Render(users[user]);
        render.batch(batch);
      }
    });

  }
});

Lazyweb Requests

These are feature requests that we would appreciate contributors for:

• Rewrite this module to have a more modular API (e.g. template caching and email queue support via kue)
• Merge with @superjoe30 swig email templates fork
• Add parsing of HTML with CSS inlining and HTML linting

Changelog

• 0.1.4 - Bug fixes, basic integration and unit tests for future iterations, abstracted templateManager, all thanks to @jasonsims

• 0.1.3 - Added support for various CSS pre-processes thanks to @jasonsims

• 0.1.2 - Added support for other template languages (ejs, jade, swig, or handlebars) thanks to @jasonsims

• 0.1.1 - Fixed long path issue for Windows

• 0.1.0 - Fixed batch documentation issue

• 0.0.9 - Fixed juice dependency issue

• 0.0.8 - Minor updates

• 0.0.7 - Added support for ejs's include directive thanks to @nicjansma

• 0.0.6 - Fixed batch problem (...has no method slice) thanks to @vekexasia

• 0.0.5 - Added support for an optional zlib compression type (e.g. you can return compressed html/text buffer for db storage)

  template('newsletter', locals, 'deflateRaw', function(err, html, text) {
    // The `html` and `text` are buffers compressed using zlib.deflateRaw
    // 
    // **NOTE**: You could also pass 'deflate' or 'gzip' if necessary, and it works with batch rendering as well
  })
  

• 0.0.4 (with bug fix for 0.0.3) - Removed requirement for style.css and text.ejs files with compatibility in node v0.6.x to v0.8.x (utilizes path.exists vs. fs.exists respectively).

Contributors

• Nick Baugh
• Andrea Baccega
• Nic Jansma (https://nicj.net)
• Jason Sims

License

The MIT License

Copyright (c) 2012- Nick Baugh (https://niftylettuce.com/)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.