Getting started

In this section you'll find features and support table, basic information about Bojler and how to use it properly. If you're first time user then you should read this first.

Typography

Introduction

Bojler is an email framework for developing responsive and lightweight email templates that will render correctly across each of the most popular email clients.

If you have experience with email template development, you know how painful it is to build a perfect email template that works across all email clients.

To make it easier for you to develop responsive and lightweight email templates we have created Bojler.

Clone, Install and Run

This is an installation process that you should follow when developing email templates with Bojler for the first time. Follow instructions step by step to get best understanding of it.

Clone the repo

Install Git Bojler uses Git as version control system and GitHub as a code hosting platform. Here you can find full installation guide on how to install Git.

Clone repository to create a local copy on your computer with this command:

$ git clone https://github.com/Slicejack/bojler.git

Install node packages

Install Node.js Bojler uses Node.js to automate SASS compile and CSS inlining. Please install Node.js before you proceed to packages installation.

Before you can use Bojler, as SASS compiler and CSS inliner with webserver and live reload, you have to install node packages with all dependencies.

Run this commands to enter newly cloned directory and to install node packages with all dependencies:

$ cd bojler # Go into newly cloned directory
$ npm install # Install node packages and dependencies

Run the Bojler πŸ”₯

Now you’re ready to run the Bojler and start working on your email template. Here is table with all the commands you can use with Bojler:

Command Description
npm run gulp This command will process and build all the files from /source to /public directory.
npm run gulp dev

This command starts development mode. While you're in development mode you have webserver with live reload, SASS compiler and CSS inlining up and running.

Bojler will process and build all files from /source to /public directory everytime you make and save changes in your .html or .scss files.
npm run gulp clean This command removes all files generated by previous 2 commands.

Features

This is a list of all the features we’ve implemented to Bojler. Few of them have their own sections in this documentation, we recommend you to read them all.

SASS support πŸŽ‰

Write SASS and Bojler will compile it to CSS. You can write your SASS inside /source/sass directory.

Make sure you have inlined.scss and embedded.scss files inside your /source/sass directory, otherwise Bojler will not be able to compile SASS to CSS.

Use existing directory structure. We recommend you to use existing directory structure. Best way to add new SASS/CSS is to import new files (partials) to inlined.scss and embedded.scss files.

Automatic CSS inlining

Some email clients strip out <head> and <style> tags from emails, so it’s best to have your CSS written inline within your markup. We know that writing inline CSS is time consuming and repetitive, so we automated it!

Bojler automatically inline your newly compiled CSS to your .html files. All you have to do is write your SASS/CSS inside inlined.scss and Bojler will take care of everything else.

What about media queries? Bojler pulls out all media queries and groups them in <head> of your .html file.

Embedded CSS

Bojler have file called embedded.scss that will embed SASS/CSS inside it to <head> of your template.

You don’t have to write media queries here, Bojler automatically groups and embed them from inlined.scss to <head>.

Webserver with Live Reload

When you run development mode Bojler starts webserver with Live Reload.

Now you don’t have to refresh your browser every time you make and save changes in your .html and .scssfiles, Bojler will do it for you.

After you run development mode your email .html files will be served at http://localhost:8000/

Reset styles

Reset styles are great starting point for your email template development. They fix all well known bugs in various email clients.

Where I can find reset styles? If you want to read more or add new reset styles you can find them in /source/sass/generic/reset.scss.

Responsive

Bojler is responsive and ready for mobile devices and tablets.

We suggest you to use this media query when building responsive emails:

@media (max-width: $breakpoint-mobile) {}

Typography

Bojler includes simple and easily customized typography for headings, table cells and lists.

To read more about Typography please go to it’s own section here.

Grid system

Bojler uses 12-column grid with a 600px container. On mobile devices (under 640px wide), columns become full width and stack vertically.

To read more about Grid system please go to it’s own section here.

Utility classes

High-specificity, very explicit selectors and helper classes. We use them to easily manipulate with things such as alignments and images.

To read more about Utility classes please go to their own section here.

Components

Components are pre-made blocks of code which you can use to build your own email template. These components are optional and other things don’t depend on them.

To read more about Components please go to their own section here.

Directory structure

Everything you want to know about directory structure can be found here:

bojler/
β”œβ”€β”€ source/ # Directory with source files that will compile to /public directory.
β”‚   β”œβ”€β”€ sass/ # Directory with SASS files that will compile to CSS and get inlined.
β”‚   β”‚   β”œβ”€β”€ components/ # Pre-made blocks of code which you can use to build your own email template.
β”‚   β”‚   β”œβ”€β”€ generic/ # Low-specificity, far-reaching rulesets (e.g. resets).
β”‚   β”‚   β”œβ”€β”€ objects/ # Objects, abstractions, and design patterns.
β”‚   β”‚   β”œβ”€β”€ tools/ # Site-wide mixins and functions.
β”‚   β”‚   β”œβ”€β”€ utilities/ # High-specificity, very explicit selectors.
β”‚   β”‚   β”œβ”€β”€ _variables.scss # All SASS variables in one place.
β”‚   β”‚   β”œβ”€β”€ embedded.scss # Embedded CSS comes from this file.
β”‚   β”‚   └── inlined.scss # Inlined CSS comes from this file.
β”‚   └── email.html # Main email template.
β”œβ”€β”€ .eslintrc # ESlint configuration file.
β”œβ”€β”€ .gitignore # Git related file which specifies intentionally untracked files to ignore.
β”œβ”€β”€ CHANGELOG.md # All notable changes to this project will be documented in this file.
β”œβ”€β”€ CONTRIBUTING.md # Contributing guide.
β”œβ”€β”€ LICENSE # Project license.
β”œβ”€β”€ README.md # Quick start guide.
β”œβ”€β”€ gulpfile.js # Gulp configuration file.
└── package.json # This file contains meta data about npm modules.

Compatibility

We have tested Bojler on numerous email clients and devices. In table below you can see what’s supported:

Email clients Web email clients Mobile devices
Apple Mail 7
Apple Mail 8
Outlook 2000
Outlook 2002
Outlook 2003
Outlook 2007
Outlook 2010
Outlook 2011
Outlook 2013
Outlook 2016
Gmail
Google Apps
Office 365
Outlook.com
Yahoo! Mail
Android 4.4
iPhone 5
iPhone 6
iPad
iPad Mini

Best practices

Follow this email CSS guide

On this link you can find a complete breakdown of the CSS support for the top 10 most popular mobile, web and desktop email clients on the planet. It is recommended to use it as often as possible.

DPI Scaling in Outlook 2007-2013

If you need to solve issues with DPI Scaling in Outlook 2007-2013 please refer to this thread and this article.

Support for VML and images is already implemented. We've already implemented solution to make VML and images scale properly, as you can see here.

Compress and optimize your images

It’s also a really great idea to try to keep your entire email as small as humanly possible: under 100kb is ideal but not always possible, under 250kb is pretty standard.

Use a compression app like compressor.io to cut all your images down to size as much as possible before you send. Slower load times, especially on mobile, can make or break your email if the overall file size is too large.

How to use images locally? We recommend you to add /assets directory containing your images inside /public directory. Bojler will not delete your /assets directory on build or during development mode.

Also npm run gulp clean command will not delete your /assets directory.

Test your email properly

Before you send your HTML email you should test it properly. We recommend you to use Litmus or Email on Acid.

Send your email properly

Best way to send your HTML email would be using an Email Service Provider (ESP) such as MailChimp or Campaign Monitor. If you’re just running a quick test we recommend you to use Putsmail.