Node.js NPM package for rendering beautiful emails with your template engine and CSS pre-processor of choice coupled with email-friendly inline CSS using juice.
NEW IN VERSION 2.4.0: Localization support has been added! You can now translate your emails for users! See Localized Template below for more info!
Enjoy this package? Build rapid startups using it with Glazed and follow and follow @niftylettuce!
- Email Templates
- Installation
- Quick Start
- Localized Template
- EJS Custom Tags
- Examples
- Changelog
- Contributors
- License
For customizable, pre-built email templates, see Email Blueprints and Transactional Email Templates.
node-email-templates uses consolidate.js, and therefore supports a vast array of template modules. Please see consolidate.js for the impressive full list.
Developing on OS X or Ubuntu/Linux is recommended, but if you only have access to a Windows machine you can do one of the following:
- Use vagrant to create a linux dev environment (recommended)
- Follow the Windows installation guide for contextify
Install email-templates
and the engines you wish to use by adding them to your package.json
dependencies.
npm install --save email-templates
# See https://www.npmjs.com/package/consolidate for a full list of available template engines
npm install -S [ejs|pug|nunjucks|handlebars|emblem|dust-linkedin|jade]
-
Install the module for your respective project:
npm install --save email-templates@2
-
Install the template engine you intend to use:
-
ejs@^2.0.0
-
jade@^1.0.0
-
nunjucks@^1.0.0
-
handlebars@^3.0.0
-
dust-linkedin@^2.0.0
-
less@^2.0.0
-
stylus@^0.51.0
-
styl@^0.2.0
-
node-sass@^3.0.0
-
See https://www.npmjs.com/package/consolidate for a full list
npm install --save <engine>
-
-
For each of your email templates (e.g. a welcome email to send to users when they register on your site), respectively name and create a folder.
mkdir templates/welcome-email
-
Add the following files inside the template's folder:
html.{{ext}}
(required) - for html format of emailtext.{{ext}}
(optional) - for text format of emailstyle.{{ext}}
(optional) - styles for html formatsubject.{{ext}}
(optional) - for subject of email
See supported template engines for possible template engine extensions (e.g.
.ejs
,.pug
,.jade
,.nunjucks
) to use for the value of{{ext}}
above.You may prefix any file name with anything you like to help you identify the files more easily in your IDE. The only requirement is that the filename contains
html.
,text.
,style.
, andsubject.
respectively. -
You may use the
include
directive from ejs (for example, to include a common header or footer). See the/examples
folder for details.
If you want to configure your template engine, just pass options.
Want to use different opening and closing tags instead of the EJS's default <%
and %>
?.
new EmailTemplate(templateDir, { delimiter: '?' })
You can also directly modify the template engine
// ...
Handlebars.registerPartial('name', '{{name.first}} {{name.last}}')
Handlebars.registerHelper('capitalize', function (context) {
return context.toUpperCase()
})
new EmailTemplate(templateDir)
// ...
You can also pass a juiceOptions
object to configure the output from juice
new EmailTemplate(templateDir, {juiceOptions: {
preserveMediaQueries: false,
removeStyleTags: false
}})
You can check all the options in juice's documentation
If you wish to disable juice, you can pass disableJuice
as an option:
new EmailTemplate(templateDir, { disableJuice: true })
You can add includePaths for sass using sassOptions.
new EmailTemplate(templateDir, {sassOptions: {
includePaths: ['~/someproject/sass']
}})
Render a single template (having only loaded the template once).
var EmailTemplate = require('email-templates').EmailTemplate
var path = require('path')
var templateDir = path.join(__dirname, 'templates', 'newsletter')
var newsletter = new EmailTemplate(templateDir)
var user = {name: 'Joe', pasta: 'spaghetti'}
newsletter.render(user, function (err, result) {
// result.html
// result.text
})
var async = require('async')
var users = [
{
email: 'pappa.pizza@spaghetti.com',
name: {
first: 'Pappa',
last: 'Pizza'
}
},
{
email: 'mister.geppetto@spaghetti.com',
name: {
first: 'Mister',
last: 'Geppetto'
}
}
]
async.each(users, function (user, next) {
newsletter.render(user, function (err, result) {
if (err) return next(err)
// result.html
// result.text
// result.subject
})
}, function (err) {
//
})
Render a template for a single email or render multiple (having only loaded the template once) using Promises.
var path = require('path')
var templateDir = path.join(__dirname, 'templates', 'pasta-dinner')
var EmailTemplate = require('email-templates').EmailTemplate
var template = new EmailTemplate(templateDir)
var users = [
{name: 'John', pasta: 'Rigatoni'},
{name: 'Luca', pasta: 'Tortellini'}
]
var templates = users.map(function (user) {
return template.render(user)
})
Promise.all(templates)
.then(function (results) {
console.log(results[0].html)
console.log(results[0].text)
console.log(results[0].subject)
console.log(results[1].html)
console.log(results[1].text)
console.log(results[1].subject)
})
Localized template folder:
templates/
templates/newsletter/
// defalt locale templates are stored in root folder and by default is en-us:
templates/newsletter/html.{{ext}}
templates/newsletter/style.{{ext}}
// for add pt-br locale:
templates/newsletter/pt-br/html.{{ext}}
templates/newsletter/pt-br/style.{{ext}}
To render the pt-br localized version for folder structure above, pass locale name in .render
method
var EmailTemplate = require('email-templates').EmailTemplate
var path = require('path')
var templateDir = path.join(__dirname, 'templates', 'newsletter')
var newsletter = new EmailTemplate(templateDir)
var user = {name: 'Joe', pasta: 'spaghetti'}
newsletter.render(user, function (err, result) {
// result.html
// result.text
})
var async = require('async')
var users = [
{
email: 'pappa.pizza@spaghetti.com',
name: {
first: 'Pappa',
last: 'Pizza'
}
},
{
email: 'mister.geppetto@spaghetti.com',
name: {
first: 'Mister',
last: 'Geppetto'
}
}
]
async.each(users, function (user, next) {
// render the pt-br localized template:
newsletter.render(user, 'pt-br', function (err, result) {
if (err) return next(err)
// result.html
// result.text
// result.subject
})
}, function (err) {
//
})
Please check the examples directory
- Nick Baugh niftylettuce@gmail.com
- Andrea Baccega vekexasia@gmail.com
- Nic Jansma http://nicj.net
- Jason Sims sims.jrobert@gmail.com
- Miguel Mota hello@miguelmota.com
- Jeduan Cornejo jeduan@gmail.com
- Alberto Souza contato@albertosouza.net
Full list of contributors can be found on the GitHub Contributor Graph