Troubleshooting & How-Tos 📡 🔍 Programming

Broken HTML Email on Lucee

If you’re building an HTML email message with Lucee, and you find weird things like broken tags or formatting, it may be due to a difference in how <CFMAIL> works in Lucee compared to ColdFusion. (TL;DR: Forced line breaks in minified code, will be fixed in Lucee 6)

And it brought back ancient memories of dealing with different email encodings that I haven’t had to deal with in at least a decade and a half.

If you’re unfamiliar with Lucee, it’s an alternate, free-and-open source (LGPL 2.1) implementation of CFML, the tag and scripting language originally created back in the 1990s to build websites with ColdFusion. After multiple rounds of corporate buyouts, ColdFusion is currently owned by Adobe.

So. Email generally is transmitted (and often stored) as plain text. Anything formatted, any images or videos or attachments, all get converted to plaintext behind the scenes and then back into your fancy newsletter or attached Excel document or whatever. And there are different ways to convert it, depending on what you’re attaching.

ColdFusion, when you create an HTML part for an email, uses a Content-Transfer-Encoding called quoted-printable. Which works great on just about any text you might throw at it.

Current versions of Lucee, however, use an encoding called 7bit. Which is more readable if you look under the hood, and handles plain ASCII fine, but isn’t going to handle much else very well. And has a sharp l000-character line limit.

Wait, 1000 characters, you say? That’s no problem! Nobody’s going to put a line that long in their email!

Well…if you have HTML and CSS formatting, and it’s minified before CFMAIL stuffs it into the message, it’s really easy to hit that limit. Add in long paragraphs relying on the end client to wrap the words?

So what happens when you toss your minified CSS and HTML into a message with Lucee? It puts a line break at every 998 characters to make sure it’s a valid 7bit message, plus an exclamation mark and a space on either side…no matter where it is in the code. Depending on where it breaks, you may have style rules that don’t work, broken HTML structure, you may have random exclamation points popping up in the message. Whatever the case, it’s not probably what you want!

This is fixed in Lucee 6.0 by just using quoted-printable, and making it possible to choose 7bit if you really want it. But 6.0 isn’t quite out yet (as of this writing, there’s a release candidate), and the latest stable 5.4 version still only uses the 7bit transfer encoding.

I’m not sure how it took until summer 2022 to spot, since my understanding is that 7bit doesn’t even handle accented letters, and the project is based in Switzerland. Even without the line break problem, there are a lot of local names that wouldn’t have been possible to send in a formatted email message.