Putting a Point on Outlook Sucking (and MJML Ruling)

The CodePen Spark is a fairly big deal for CodePen. It goes out every week to millions of developers. The 2nd most popular email client to open The Spark is Outlook, just behind Gmail. You probably know this: Outlook is the worst. It’s solely the thing that keeps HTML email development painful. The thing that requires <table> markup because of how many limitations it has. Without it, HTML email development could take a leap forward.

Just “Outlook” isn’t quite fair though, it’s “Outlook that uses the Microsoft Word rendering engine”, which is a subset of Outlook email clients. The gist of it is: Outlook as a Native Windows app. If it’s on Mac, it’s fine. If it’s on the web, it’s fine. But Outlook on Windows is still mega popular, so here we are. Let’s hope One Outlook actually pans out. I’ll just continue to say “Outlook” in this post, but what I mean is the bad Outlook(s).

In our latest CodePen Spark template, I basically ignored Outlook. I used normal <div>s and CSS and essentially designed a simple modern website, media queries and all, as the email. But we got just enough reports from Outlook users that it bugged me. The layout wasn’t just a little bad, it was super duper bad.

So I figured I’d try to fix it. I didn’t feel good to leave behind what I consider pretty normal and mostly semantic markup for whatever the hell Outlook needs, but hey, the job is delivering good experiences, not theoretical purity.

MailChimp has some very old but very still functional email templates on GitHub, so I started there. Look at that beauty. That would work for our basic 2-column format. I started with this and actually got pretty far just doing it all by hand. I’d make a bunch of changes trying to get the template in shape, then test it all in Litmus to check if I was on the right track.

This was going fine for a while, it just was finicky as all hell. After poking around at it for weeks trying to get it into really solid shape, I ultimately decided all this was just way too much technical debt to take on. The complication was too high, I would be the only one who really understood what mattered in this massive awkward template, and maintaining it would be too much to ask.

MJML has been on my radar for a while, so I thought I’d give that a go instead. Rather than author directly in HTML, you use tags like <mj-section> and <mj-image> and it processes into HTML that is Outlook friendly.

I’m pretty sold on @mjmlio after trying to fight Outlook problems manually too long.

Authoring right in VS Code with a preview is pretty sweet.

NOTE: Use the “MJML (unofficial fork)” VS Code plugin, not the official one which is pretty busted. pic.twitter.com/zLCHafDI2a

— Chris Coyier (@chriscoyier) September 21, 2022

The fact that you can author the email with a preview right in VS Code is pretty damn great. But most importantly, despite MJML being yet-another-tool-in-the-chain, I think the technical debt is quite a bit lower.

• It took the new email template I was working on from something like 800-900 lines of code to 160 of easy-to-look-at code.
• I was able to break off some of the bespoke CSS into a separate file, which is just cleaner to work with.
• MJML has actual documentation.

Anyway, I’d consider it a big win. (Sorta tempted to keep piling on and try Mailing too, which is MJML under the hood but abstract and adds with React + Typescript, but enough tooling for one round).

But again why did we have to go down this road? Outlook. Bad.

I feel like it’s worth putting a clear point on:

• You cannot use normal <div>s because Outlook ignores CSS applied to them. Like width and padding. So you can’t use them as nice section chunks and definitely not as columns parents. So when people say “HTML email still uses tables!” they mean it, you literally have to use <table> and children to do even basic styling of things.
• You have to add the width attribute directly on images. It ignores CSS applied to images (no width, no padding, no margin), so you can’t count on CSS to help control the layout of images. Forget one, it’ll probably destroy your entire email.
• Now that you’ve just learned to use like width="600" on images, don’t do that on anything else. If you need to assign a width to, say, a <table> you should do <table style="width: 600px;"> because of awkward auto-scaling issues that can kick in.
• Don’t expect anything fancy whatsoever. Don’t try the checkbox hack. Even animated GIFs don’t work.

Surely there are more, but those things alone are just the worst. The make hand-authoring dang near out of the question to me, since it’s ridiculously error-prone.