email-builder-core
Email builder core for export into other projects
Constructor
new EmailBuilder(options)
Example:
var EmailBuilder = ;var 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 : 'toEmail@email.com' // Email sent from from: 'fromEmail@email.com' // 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 file
string
- String of HTML
buffer
- 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 ;
emailBuilder.sendLitmusTest(html)
Send tests to Litmus.
Arguments
html
- String/Buffer of HTML
Example:
var fs = ;var file = fs;emailBuilder ;
emailBuilder.sendEmailTest(html)
Send email tests to yourself
Arguments
html
- String/Buffer of HTML
Example:
var fs = ;var file = fs;emailBuilder ;
Complete Example
input.html
<!-- styles will be inlined --> <!-- styles will be embedded --> <!-- link tag will be preserved and styles will not be inlined or embedded --> <!-- styles will be inlined --> <!-- styles will be embedded --> Heading Body
main.js
var fs = ;var EmailBuilder = ;var options = encodeSpecialChars: true litmus: ... emailTest: ...;var emailBuilder = options;var src = process + '/input.html'; emailBuilder catch{ console; };
out.html
Heading Body
Testing
gulp test
- Runs jshint and mocha tests
gulp 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.