Space Panda

HTML Email

HTML in emails is a bit of a curse. And yet, some people have set their email program to not use monospace fonts to display emails which makes sending tables inside of an email a bit of a problem 1.

Luckily there is such a thing as multipart/alternative that allows you to write emails in plain text and attach another HTML file as the alternative for those with questionably configured MUAs.

To avoid writing emails twice, once in plain and once in HTML, here’s how to utilise pandoc to automatically convert your plain text into HTML and attach it to the email.

Note that these instructions are for neomutt. For mutt have a look at send_multipart_alternative and the matching send_multipart_alternative_filter.

The easiest and most direct approach in neomutt is this to:

  1. Pipe the written text into pandoc,

  2. Attach the generated file,

  3. Tag both, plain text and generated file,

  4. Group them as multipart/alternative

# ~/.config/neomutt/neomuttrc

macro compose C "<pipe-entry>pandoc -s -t html -o /run/user/`id -u`/draft.html<return>\
                 <attach-file>/run/user/`id -u`/draft.html<return>\
                 <group-alternatives>"  "Convert to text/html as multipart/alternative"

This particular macro saves the generated file in /run/user/\`id -u\`/draft.html because it’s in RAM and user specific.

The input format

In this script pandoc will assume that the input has been written in Markdown. Good for some, but I prefer using reStructuredText 2 because the tables are a bit nicer in plain text.

To tell what input format to expect, add the -f flag to your call to pandoc:

pandoc -f rst -s -t html --metadata title=- -o /run/user/`id -u`/draft.html

The --metadata title=- is only there to prevent a warning from pandoc about the missing title.

Refining the output HTML

By default the HTML generated by pandoc will have a fancy <H1> title, which is good for documents, but not that great for emails. Unless you like to yell at your recipients.

To prevent it, you can generate your own HTML template by first obtaining the default HTML template from pandoc:

pandoc --print-default-template html > ~/.config/neomutt/email.html

Now you can remove the extra code that you don’t want added to your email (like the 3rd party style include for Internet Explorer style fixes) and add your own style sheet, if you want.

Once the template is prepared, you will have to tell pandoc to use it:

pandoc -f rst -s -t html --metadata title=- --resource-path=$HOME/.config/neomutt --template=email.html -o /run/user/`id -u`/draft.html

So, this is it. But remember, with great power comes great responsibility: only send HTML emails if absolutely necessary.

Happy mailing!


Arguing whether or not this would better be solved by attaching the tables in an appropriate file format to the email is best left to other formats than a blog.


Whether to use reStructuredText or Markdown is a matter of taste; it should be easy to change the scripts and setup to use Markdown if you prefer.

Tagged as html, mutt, neomutt, pandoc