Painless HTML email coding

How to code an email and not die out of frustration.

Maciej Matuszewski
May 28, 2018 · 6 min read

Front-end development is fun and all until you have to style your first HTML email template. You think, “It’s just HTML… It can’t be THAT hard…”

It’s more complicated than it seems. Email clients vastly differ in their support for, even really simple, HTML and CSS features. It’s really upsetting when you find out that your beautiful creation is displayed incorrectly in 80% of mail clients…

A lot of people, also tend to forget about responsiveness. According to Litmus 2017 report, iPhone mail client, has the biggest market share (28%) and just after it, there is GMail(26%). It means that responsive email is no longer a nice addition, but it also became a necessity.

I avoided this topic for a long time, but it finally got me. I had to style a simple email, and after about 5 or 6 iterations, where I fixed something and somebody reported yet another issue with the layout, I had a feeling that it was really repetitive.

And we all know what programmers do with repetitive tasks:

Znalezione obrazy dla zapytania automate all the things

First thing I did was ask my good friend Google, what does he think about that. As always he had some great answers for me. After a while I had a sense of what the choices I had. I could either use an existing HTML template and modify it or use an email framework.

I set out to find the holy grail of email templating, and I established a couple of requirements that would make email development nice or even pleasurable:

  1. Avoid direct contact with HTML tables as much as possible.
  2. Supports most major email clients
  3. A better alternative to inline-styles.
  4. Ability to remove duplication as much as possible
  5. Easy to add responsive layout

Using a pre-made template

This was my first choice since I wanted to spend as little time as possible on the task. This way, I could use something that looks good and was already tested. I found a couple nice email templates on cakemail website, but it still wasn’t exactly what I wanted. The customization process was painful because of all the chaos in the html file. Changing images, colors and text would be quite exhausting and not that fast.

I needed to find something better. which lead me to find two email frameworks.

Using an email framework

Email creation frameworks provide a set of tools that make the development a lot nicer. They usually provide a custom syntax for the mail template, some ready components and development tools.

Two popular email frameworks that I found are Foundation for Emails and MJML (Mail Jet Markup Language). I chose MJML for my project because it is better suited for node based projects. Foundation Emails framework is really similar and easy to use.

I will focus mostly on MJML because it’s the one I have experience with, but it’s possible that Foundation Emails has the same, or even better features remember to check that by yourself before choosing the solution that fits you.

Foundation Emails

This project was created by ZURB Foundation and previously was known as Inky. It still uses Inky as a templating language, but they added a lot more, such as Sass styling, responsive grid, and common UI patterns to help you speed up development. The documentation is well written, and there are multiple great example templates provided. A simple responsive email would look like this:

Foundation for Emails feels really robust. I didn’t have a chance to actually try it out but I feel like I would be happy with this choice.


It’s an abbreviation of Mail Jet Markup Language. It’s a tool created by Mailjet (duh…) for their tool called Passport, an interactive email creator. According to Nicolas Garnier who is on the MJML team, the platform is currently the most used responsive email library worldwide, which is quite an achievement! It is also used by giants such as The New York Times and Ryan Air.

If you have some experience with HTML, you’ll feel right at home. This is what an example template looks like:

Looks simple, right?

From the technical point of view, it’s not that different from Foundation Emails. Main differences are that all the tags are prefixed with <mj-*> and you can style by using tag attributes not sass.

This tool is exactly what I was looking for since it fits all my requirements:

  1. Avoid direct contact with HTML tables as much as possible — MJML provides it’s own XML inspired syntax, that is plain simple. Waaay better than writing a shitload of <td>'s.
  2. Supports most major email clients — MJML compiles to plain html (tables) and they support most major clients out of the box. You can find detailed support in their docs. They even have those awesome compatibility charts similar to what CanIUse has.
  3. A better alternative to inline-styles — How about writing them as attributes? Some people may dislike this solution but for me, it worked just fine. The html might get a bit long, but it’s possible to avoid it by using custom MJML attributes and classes which is the next point.
  4. Ability to remove duplication as much as possible — This is where custom attributes and classes shine. It’s possible to define reusable classes and global settings for tags. This way most of the duplication can be removed. Sprinkle some Handlebars templating on it, and you will be looking forward to the next emails to style!
  5. Easy to add responsive layout — MJML supports columns, and even custom breakpoints
  6. (BONUS POINT!) Custom Components — You can easily create them. That might be helpful for more robust templates.
  7. (BONUS POINT!) Toolchain — There are plugins for major IDE’s, and there is even a dedicated editor that simplifies template creation. That’s just amazing.
  8. (BONUS POINT!) Predefined Components — Did you know that you can add a Carousel and Accordion components to your email? DID YOU? I mean, that’s just crazy… And you get if for free. Blew. My. Mind.

So Yeah… This tools saved me a headache and a lot of hours. It’s really amazing, and I encourage you to try it out. There are a couple of free templates that can help you get started. I especially like the UGG Royale one. It looks really professional and shows most of the cool and useful features of MJML.

If you want to dig deeper into actual implementation I recommend this smashing magazine article, and of course, the official documentation.

Tap the 👏 button if you found this article useful, and if you did, go ahead and share it with somebody! They might find it useful 😄.

Let’s not forget about Foundation for Emails. If you had some experience with it, feel free to share it in the comments below. I would love to hear how it differs from MJML.


apps & more

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store