email-builder-core
v2.1.2
Published
Email builder core. Provides useful methods to inline css, send tests to Litmus and send email tests
Downloads
9,843
Readme
email-builder-core
Email builder core for export into other projects
Constructor
new EmailBuilder(options)
Example:
var EmailBuilder = require('email-builder-core');
var emailBuilder = new EmailBuilder({ encodeSpecialChars: true });Options
The following options may support all available methods of EmailBuilder. However there some that are only needed for a particular method.
options.encodeSpecialChars
Type: Boolean
Default: false
Supported Method(s): All
Encodes special characters to their HTML numerical form e.g. © --> ©
options.relativePath
Type: String
Default: ''
Supported Method(s): emailBuilder.inlineCss
This option must be set when passing a Buffer or a String to the inlineCss method. That way it has a relative path to any css files. The path should be whatever directory your src file is in.
options.litmus
Type: Object
Default: {}
Properties: username, password, url, applications
Supported Method(s): emailBuilder.sendLitmusTest
Example:
litmus : {
// Optional, defaults to title of email or yyyy-mm-dd if <title> and options.subject not set
subject : 'Custom subject line',
// Litmus username
username : 'username',
// Litmus password
password : 'password',
// Url to your Litmus account
url : 'https://yoursite.litmus.com',
// Email clients to test for. Find them at http://yoursite.litmus.com/emails/clients.xml
// The <application_code> tags contain the name e.g. Gmail Chrome: <application_code> chromegmailnew </application_code>
applications : ['gmailnew', 'hotmail', 'outlookcom', 'ol2000', 'ol2002', 'ol2003', 'ol2007', 'ol2010','ol2011', 'ol2013', 'appmail8', 'iphone5', 'ipad3']
}options.emailTest
Type: Object
Default: {}
Properties: to, from, subject, nodemailer
Supported Method(s): emailBuilder.sendEmailTest
The optional nodemailer property is an object that has transporter and defaults properties. These get passed to the nodemailer.createTransport() method. You can use transport plugins or play with the default SMTP options for the nodemailer.transporter property
Example:
emailTest : {
// Email to send to
to : '[email protected]',
// Email sent from
from: '[email protected]',
// Your email Subject
subject : 'Email Subject',
// Optional
nodemailer: {
transporter: {
service: 'gmail',
auth: {
user: 'gmailuser',
pass: 'gmailpass'
}
},
defaults: {}
}
}options.juice
Type: Object
Default: {}
Supported Properties: extraCss, applyWidthAttributes, applyAttributesTableElements
Supported Method(s): emailBuilder.inlineCss
View Juice options
options.cheerio
Type: Object
Default: {}
View Cheerio options.
Methods
All methods return a promise, the underlying promise library we use is Bluebird. Methods can be used seperately, or chained together using the .then method. If you're not familiar with promises, instead of using a callback, you chain a .then method to get the results.
emailBuilder.inlineCss(file/html/buffer)
Inlines css from embedded or external styles. It'll automatically remove any link or style tags unless one of the data attributes below are used. View test fixtures to see examples.
Arguments
file - String containing path to filestring - String of HTMLbuffer - Buffer of HTML
HTML data attributes
There are two supported data attributes that you can apply to <style> or <link> tags that have special meaning:
data-embed
- use on <style> or <link> tags if you want styles to be embedded in the <head> of the final output. Does not inline css
data-embed-ignore
- use on <link> tags to preserve them in the <head>. Does not inline or embed css
Example:
emailBuilder.inlineCss('path/to/file.html')
.then(function(html){
console.log(html);
});emailBuilder.sendLitmusTest(html)
Send tests to Litmus.
Arguments
html - String/Buffer of HTML
Example:
var fs = require('fs');
var file = fs.readFileSync('path/to/file.html');
emailBuilder.sendLitmusTest(file)
.then(function(html){
console.log(html);
});emailBuilder.sendEmailTest(html)
Send email tests to yourself
Arguments
html - String/Buffer of HTML
Example:
var fs = require('fs');
var file = fs.readFileSync('path/to/file.html');
emailBuilder.sendEmailTest(file)
.then(function(html){
console.log(html);
});Complete Example
input.html
<!DOCTYPE html>
<html>
<head>
<!-- styles will be inlined -->
<link rel="stylesheet" type="text/css" href="../css/styles.css">
<!-- styles will be embedded -->
<link rel="stylesheet" type="text/css" href="../css/otherStyles.css" data-embed>
<!-- link tag will be preserved and styles will not be inlined or embedded -->
<link href='http://fonts.googleapis.com/css?family=Open+Sans' rel='stylesheet' type='text/css' data-embed-ignore>
<!-- styles will be inlined -->
<style>
p { color: red; }
</style>
<!-- styles will be embedded -->
<style data-embed>
h1 { color: black; }
</style>
</head>
<body>
<h1>Heading</h1>
<p>Body</p>
</body>
</html>main.js
var fs = require('fs');
var EmailBuilder = require('email-builder-core');
var options = {
encodeSpecialChars: true,
litmus: {...},
emailTest: {...}
};
var emailBuilder = new EmailBuilder(options);
var src = process.cwd() + '/input.html';
emailBuilder.inlineCss(src)
.then(emailBuilder.sendLitmusTest)
.then(emailBuilder.sendEmailTest)
.then(function(html){
// can write files here
fs.writeFileSync(process.cwd() + '/out.html', html);
})
catch(function(err){
console.log(err);
});out.html
<!DOCTYPE html>
<html>
<head>
<link href='http://fonts.googleapis.com/css?family=Open+Sans' rel='stylesheet' type='text/css'>
<style>
h1 { color: black; }
</style>
</head>
<body>
<h1>Heading</h1>
<p style="color: red">Body</p>
</body>
</html>Testing
gulp test - Runs jshint and mocha testsgulp inline - Inlines css from test/fixtures/input directory and creates the test/fixtures/output directory. Run if you add/update any fixtures in the test/fixtures/input directory.
Troubleshooting
If you're having issues with Litmus taking forever to load a test or the title of the test is showing up as "No Subject", it is most likely an issue with the Litmus API. You can check the Litmus status page to find out if their having any issues. If that's not the case, submit an issue and we'll look into further.
Thanks to
Juice for compiling.