Premail NPM | npm.io

MJML is a markup language for writing bulletproof HTML emails. It intentionally doesn't include a build process. This is that build process, and it's configurable to meet your needs and catch the edge cases.

Premail is component-based, and uses Handlebars for templating. Settings are defined in YAML configuration files, and theming happens in a design configuration file as well as (optionally) Sass files.

Email templates are all valid under MJML version 4.

One index.html file will be rendered, as well as (optionally) a plain-text version, ready to import into your emailer of choice. See an example of the default layout.

Read more at a quick introduction to Premail.

Features

MJMLv4-standard bulletproof code that will look its best across all email clients, reduced to the smallest possible size. CSS is inlined and HTML is minified as with all MJML, but we also add some extra checks, for instance, to make sure emojis are properly escaped and the file size doesn't hit Gmail's clipping limit.
Component-based templates that allow you to separate out things that don't often change (navigation menus, social media links, unsubscribe text) and things that will usually change (a header or banner, preheader text, and the main body of the email).
You can create multiple designs, and each time you create a new email you can choose from among your existing designs. This allows you to keep the structure of the design and the content of the email separate, and reduces errors.
As you're creating a design or crafting a new email, you can use a watch task to automatically recompile the result.
Within each design, the CSS (created in Sass files) is automatically inlined in the HTML, thanks to MJML. Additionally, stub files exist for including pseudo-CSS styles (such as hover states) for email clients that support them, as well as styles specifically targeting Gmail.
A plain-text version of your email is optionally created, and Premail does a much better job than most email services at rendering it. While only a small number of your recipients will see the plain-text version, they are important for email deliverability. Within the plain-text version options, you can control whether certain elements like navigation or header/banner areas are included.
Configuration files are written in YAML, making them easy to read, and comments -- with links to relevant resources -- are included throughout.
Perfectly structured for including in a git repo -- don't rely on your email service provider to keep an archive of your past emails! And Prettier is included to automatically clean up template formatting for easier file-diffing.

When it comes to the content of your emails, optional enhancements can be controlled per-email:

Transforming quotes, apostrophes, and dashes to their correct typographical versions; optical character alignment; and true small-caps formatting with Detergent and Typeset.
Enforcing proper image alt tags and making sure the supplied text doesn't break email code parsers.
Padding preview/preheader text to prevent things like navigation menu items from being visible in a recipient's inbox.

Feel free to make suggestions for more enhancements!

Custom MJML components

Premail also includes some MJML custom components for common use cases:

MJML Bullet List
MJML Signoff

Setup and usage

Premail requires Node 12.x or 14.x to run. See the Premail setup documentation for details.

Installation

npm install -g premail

That's it! See setting up Premail for additional installation options.

Quickstart

Install Premail (above).
Create an emtpy directory and enter it on the command line.
Run premail init. This generates the Premail scaffolding and includes an example design and email source.
Run premail build -e _example. This builds the example email.
Take a look at emails/_example/dist to see the built HTML and plain text versions of the email.

Head over to the Premail Usage Guide to start learning about how to use Premail with your own designs and emails.

CLI options

You can run premail -h to see the full list of options:

Usage: premail <command> [options]

Commands:
  premail new <email|design> <dest>  Create a new email or design in <dest>
  premail build                      Build an email
  premail watch                      Watch design and configuration files and
                                      rebuild as necessary
  premail clean                      Remove generated files from the current
                                      design or email
  premail paths                      List paths being used with the current
                                      configuration and command-line flags
  premail format                     Format templates with Prettier
  premail init                       Initialize a Premail project
  premail destroy                    Destroy this Premail project

Email development:
  -d, --design    Specify design directory to use [string] [default: "_default"]
  -e, --email     Specify email directory to use                        [string]
  -p, --prod      Render production files (minified, no comments)      [boolean]
  -s, --noserve   Disable serving rendered email via browserSync       [boolean]
  -f, --noformat  Disable auto-formatting of files using Prettier      [boolean]
      --debug     Append to any command to see verbose details         [boolean]

Design development:
      --temp  Include intermediate rendered template (post-Handlebars, pre-MJML)
              in output                                                [boolean]

New emails and designs:
  -d, --design  Specify design directory to use   [string] [default: "_default"]
  -e, --email   Specify email directory to use                          [string]

More information:
  -v, --version  Show version number                                   [boolean]
  -h, --help     Show help                                             [boolean]

Additional documentation: https://premail.dev

Project information

Documentation

Detailed documentation and guides are available at https://premail.dev.

Roadmap

See the open issues for a list of proposed features and known issues, and projects to see them grouped by major release.

Top feature requests (Add your votes using the 👍 reaction)
Top bugs (Add your votes using the 👍 reaction)
Newest bugs

Premail's changelog includes unreleased features and fixes, in addition to recording what changed in each past release.

Getting support

Ask a support question on GitHub if you're stuck.

Helping out

If you want to say thank you and support active development of Premail:

🌟 Add a GitHub Star to the project.
Tweet about Premail (@premaildev on Twitter).
Consider sponsoring rootwork, Premail's developer, and have your name or logo included here!
Blog about the project. We love reviews, and are eager to hear ways we could make things even better.

Contributing

First off, thanks for taking the time to contribute! Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are greatly appreciated.

Please read our contribution guidelines, and thank you for being involved!

Security

Legalese: Premail is provided "as is" without any warranty. Use at your own risk.

For more information and to report security issues, please refer to our security documentation.

Thanks and Sponsorships

Work funded in part by Multi-Etch, LLC.

Consider sponsoring rootwork, Premail's developer, and have your name or logo included here!

Premail is built on all sorts of open-source code. Our appreciation to all of these fine projects!

License

Premail itself is licensed under the GNU Affero General Public License v3.0 or later. To be clear: This license only covers Premail, not any content you generate using Premail. Those files are yours to do with as you wish, and you need not share them, much less license them, in any particular way.

For the legal details of the AGPL, see the complete LICENSE.

The Premail.dev website, meanwhile, is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.