bryantaylor/html-email-starter

Email coding guidelines & Gulp workflow for creating HTML emails

Ripe's starter email workflow

Our "Starter Email" is based on the Gulp Email Creator by Daryll Dole, which was inspired by Lee Munroe's grunt-email-design workflow.

It aims to help speed up email template production by allowing you to use SCSS and inlining the generated CSS for you. We've added support for Jade to compile the markup

Workflow Overview

The gulpfile is the engine of the workflow. It does the following:

• Compiles templates from Jade to HTML
• Processes SCSS into CSS
• Inlines CSS into HTML via MailChimp Inliner
• Outputs HTML with inlined CSS to an ./output/ directory
• Send test emails to any inbox via Mailgun
• Delivers email to directly to a Litmus test

Design Resources

• MailChimp's Email Design Reference is a very handy resource
• Read through this and this before you start any coding.
• Handy code snippet for buttons here
• More reading on coding buttons. Litmus's bulletproof buttons
• MailChimp Merge tags cheatsheet
• See MailChimp's Email Blueprints or Responsive Email Patterns for design patterns.

For more information on web fonts, image blocking, width, CSS support, etc check out Campaign Monitor's Design Guidelines, which features a handy table on CSS support

Installation

You need to have both Node.js and Gulp.js installed .

You can install it by cloning this repository to a local folder and running the following from inside the directory.

    npm install

This will install all dependencies.

If the install fails try running the install as root. For some reason browsersync seemed to fail for me unless installed as root.

    sudo npm install

Configuration

You need configure a few basic settings before use. This tool relies on a config.json file

• Rename config.default.json to config.json
• Add MailChimp API key. This workflow uses their free CSS inliner. API Key Instructions Here
• Add to/from email addresses. This will be used by Mailgun to send tests.
• 'To' can have multiple email addresses. They should be comma separated.
• Subject line should be '{{Client}} {{Project Name}} (test {{test no}})'
• Add Mailgun credentials for testing. These are found by click on "Domains" in your Mailgun dashboard. Login usually begins with postmaster@sandbox....
• Add Litmus static email address to automatically send the design to a Litmus test

Using the package

You can use this email creator workflow by creating your HTML in the ./src/html/ directory and your SCSS in the ./src/scss/ directory.

Compile Templates

Running gulp from the terminal will build the new HTML email template into the ./output/ directory and the proceed to watch ./src/html/ and ./src/scss/ for any updates.

You can write your templates in either Jade or HTML. The default gulp task will look for Jade templates in ./src/jade/ and compile them to ./src/html. Any changes to HTML will build and reload via BrowserSync. The workflow doesn't care if those changes come via compiling Jade or if you write the HTML manually.

The gulpfile has browsersync built in and will reload on any HTML or CSS edit, allowing you to focus on your code.

Sending the Template to yourself

Running gulp send will allow you to send the compiled template to yourself through Mailgun (you'll need to sign up for a free account). The settings for this can be found in the config.json file.

To run this, you can use the following command

gulp send --template="compiled-template-name.html"

Testing

Thanks to the awesome guys over Litmus, we can now throw your emails straight into their tests. You'll need an active Litmus account (well worth the money!) and to get your static email. Plug this into the config.json file and then run the following command.

gulp litmus --template="compiled-template-name.html"

In a few seconds/minutes, you'll see the test appear in Limus for you!

Contributing

Any contributions will be happily received. Just open an issue or make a pull request.