Jurassic Markup: Surviving Custom Email Template Development

I was recently tasked with developing a custom email template for an internal company newsletter. When shown the simple design mockup, my brain, still in React-mode, gave my manager an estimate of 2 weeks maximum, alongside my usual client work, to have the template ready for use. A few simple containers holding text and image content– it sounded like Web Development 101. Experienced email devs reading this are either laughing, or wincing in pain. Over the next few weeks I would learn that I had made a disturbingly insufficient time estimate, and incorrectly assumed that any tools and methods from modern web development would be of use to me. Read on and we’ll dig into why email, the technological dinosaur that survived, is one of the most challenging platforms to develop for.

What I learned in the following weeks was that email developers operate under prehistoric HTML and CSS pretenses and deal with mind-numbing client compatibility woes. Getting a simple single-column, 6-row table of text and images adhering to basic modern design principles to render consistently across a few popular email clients, would indeed require several hundred test emails to myself. I’d repeatedly fix a problem in one client only to find it had unleashed a new one in another. There’s a reason tools like Litmus, which let you mass-preview an email across devices and clients, start their pricing at $500 per month for even the most basic plans. A lot of time, effort, and money goes into developing emails, which isn’t surprising given their still-huge role in marketing and advertising.

So, what makes the job so challenging? Emails at their core are nothing but text and HTML, split into headers and a body. Even attachments are just base-64 encoded blobs (yes, that’s both ancient and inefficient). Well, each platform and client brings to the table its own filter for what gets through, and developer documentation is often nonexistent across the board. Webmail is rendered by the browser, Apple Mail uses WebKit, Android uses chromium-based components, and Outlook, the biggest beast of them all, uses Microsoft Word’s HTML engine (yes, really) on Windows. Get ready to kiss your divs, flexboxes, and @media queries goodbye. Many clients, including Gmail in certain contexts, aggressively sanitize or strip <style> blocks. I don’t have to explain why JavaScript isn’t allowed in email, but even CSS is heavily limited, as modern CSS can load remote resources, leak data via url(), detect user behavior, fingerprint devices, crash renderers, and execute browser bugs.

And so the picture becomes clearer…

The crux of the matter is, if you want your email to look consistent on every platform and in every client, it needs to use markup and styling that is compatible with literally everything, and leaves no room for security breaches. The site caniemail is a great tool for checking compatibility of HTML and CSS in emails, and at the conclusion of this article I offer a few do’s and don’ts that will hopefully save some headaches for others new to email development.

But first, you may wonder, why hasn’t anyone invented a better way? Why was there never an Email 2.0? Why hasn’t the technology grown to better mirror modern web presentation? The answer is two-fold. First, email is federated; nobody owns it. Anyone can run a mail server and communicate via open protocols (like SMTP). As soon as that’s given up, it stops being a universal messaging protocol and becomes a corporate product with terms of service. Email must continue to offer a universal addressability contract. As soon as a message delivery system becomes centralized, it faces data retention laws, content moderation obligations, and jurisdiction problems. Furthermore, it’s hardly the most exciting ecosystem to develop for. Email can’t break old servers, old clients, ancient mail transfer agents, or embedded systems. If a successor to email can’t talk to banks, governments, hospitals, and universities, it’s dead on arrival. Email’s knockout feature isn’t the tech– it’s the unbreakable social contract and Grade-A backwards compatibility.

Secondly, although undeniably first in importance, is security. In the 90s, spam changed everything, and modern email systems are more hostile-environment filtering engines than they are message delivery protocols. While I still recall the ‘You have 7 days to forward this to everyone you know or bad things will happen’ emails with a certain humorous, nostalgic fondness (my grandpa forwarded every single one of them to me), spam tactics have since grown far more complex, and weeding out bad actors involves a smorgasbord of systems at work: authentication, sender and domain reputation, user engagement signals, content heuristics, and ML classification. As it’s grown more difficult for bad actors to take your information via email, spam has grown in the latter half of email’s lifetime to employ phishing-centric approaches, requiring the user to give it away. Further discussion on security and spam filtering definitely warrants its own article, but for now consider email clients as not as rendering engines, but security filters that sometimes render HTML.

As I took on the task of developing a custom email template with the goal being any semblance of consistency, my frustration initially grew a mile tall– clearly, it was enough to write an article about it in the aftermath– but in hindsight, I’m left with a respect for a communicative technology that revolutionized the world over half a century ago, has since quietly grown to be nearly bulletproof in the modern day, and remains a staple of communication in daily life. There’s really nothing else quite like it, and it’s a subject I’m glad I explored further. As promised, I’ll leave you with a starter pack of do’s and don’ts for developers on their first journey through email wonderland:

• Keep it simple. If you have control over design requirements, a single column, fixed width design not requiring wrapping beyond text will save you many headaches.
• Lean on <table>s for layout. Use role="presentation", cellpadding="0", cellspacing="0", and border="0" on each of them within your nest to fight back against default table styling in clients.
• Avoid usage of div if possible; it’s supported on paper but has been known to be inconsistent in Outlook.
• Entertain web fonts as progressive enhancement, but don’t lean on them as critical design; always include a system font fallback.
• Slap an !important on any styles you see disappearing between send and receipt. With some luck, the client gremlins that live within will allow them to pass.
• Consider embedded CSS for a tad less development pain over inline styles, but utilize an inlining tool before shipping, as some clients will strip out <style> completely. Platforms like Mailchimp offer built-in inlining tools.
• Test dark mode in clients and operating systems carefully, as some will wildly guess at how to replace colors when turned on.
• Utilize tools as your budget allows. Litmus and Email On Acid allow you to test quickly and broadly, and frameworks like MJML and React Email allow you to build in a manner you’re more familiar with while ultimately boiling down to email client friendly markup and styling.

• Rely on flexbox, grid, absolute positioning, advanced selectors, or external stylesheets. Support is inconsistent across clients.
• Assume images will load. Many clients will block them by default.
• Embed text in images. This is a sneaky tactic marketing emails use to maintain fancy style, but it’s bad for accessibility. Your email should be readable without images.
• Rely on margin for layout. Margins often collapse or disappear in Outlook. Utilize padding, spacer <td> cells, and explicit height tables.

Whether these field notes found their way to you out of a cry for help, or you stumbled upon them during a curious venture down a rabbit-hole, I hope they provide you some utility or a dash of perspective into a dinosaur technology that survived to the modern day. For further reading on the wonderful world of web, check out our other articles on Livefront.com .

• Andrew VanderLeest

  Software Engineer

  More from Andrew