--- title: "Multipart Emails in Neomutt" tags: - Mutt description: Mutt now supports multipart email. I guess it will be easy to set it up right? date: 2022-05-27 --- It recently came to my attention that mutt now supports sending multipart emails. I thought that this would mean that in half an hour or so I would have html emails working. Turns out, I was wrong. What instead happened was weeks of trial and error and reading RFCs. I now have a system I am happy with. I write an email in markdown and mutt (along with some surrounding scripts) will convert that markdown to html, attach inline images and create a multipart email. ## A note about HTML emails If you do need to send HTML emails, please spare a thought for your recipient; it is not just "weird" terminal email client users that could suffer. According to the [National Eye Institute](https://www.nei.nih.gov/learn-about-eye-health/eye-conditions-and-diseases/color-blindness), one in twelve men are colour blind; so please don't use only colour to distinguish items. Additionally, many people suffer from vision-loss blindness, who are likely to use screen readers or braille displays. Complex layouts or heavy use of images are going to give these people a poor experience. That being said, HTML emails can be used for aesthetic purposes, whilst still providing a plain text version for those who want it. That is the method I suggest adopting if you need html emails, and the method this blog post will describe. ## Multipart / Related emails To begin with, we need to understand a little bit about how emails are structured. Below is an example tree structure of a standard email. ``` Multipart Related ├─>Multipart Alternative │ ├─>Plain Text Email │ └─>HTML Email └─>Inline Image Attachment Non-Inline Attachment ``` Starting at the lowest level, we see a plain text email and an HTML email. These are both wrapped in a multipart **alternative** wrapper. This tells email clients receiving the email that they are alternative versions of the same document. The email client will normally choose which to display based on the mime type and user preferences. The multipart alternative wrapper and an image attachment are then wrapped in a multipart **related** wrapper. This tells the email client that the contents are related to one another, but not different version of the same document. This is where inline images are attached. Finally, there is another attachment that is outside of the multipart related wrapper. This will show up as another attachment but cannot be displayed inline. ## Neomutt Configuration The conversion from markdown to html will be handled by an external script. It will create files and instruct mutt to attach them. We can start with the following: ```vimrc macro compose Y "\ convert-multipart\ source /tmp/neomutt-attach-macro ``` We specify a macro to run when `Y` is pushed. First, we select the first entry. This is in case we have attached anything manually, the first entry should be the markdown file. We then pipe the selected entry (the markdown file) to an external script, in this case a bash script called `convert-multipart`. Finally we source a file called `/tmp/neomutt-commands`. This will be populated by the script and will allow us to group and attach files inside neomutt. ## Converting to HTML Let's start with a simple pandoc conversion. ```bash #!/usr/bin/env bash commandsFile="/tmp/neomutt-commands" markdownFile="/tmp/neomutt-markdown" htmlFile="/tmp/neomutt.html" cat - > "$markdownFile" echo -n "push " > "$commandsFile" pandoc -f markdown -t html5 --standalone --template ~/.pandoc/templates/email.html "$markdownFile" > "$htmlFile" # Attach the html file echo -n "\"$htmlFile\"" >> "$commandsFile" # Set it as inline echo -n "" >> "$commandsFile" # Tell neomutt to delete it after sending echo -n "" >> "$commandsFile" # Select both the html and markdown files echo -n "" >> "$commandsFile" # Group the selected messages as alternatives echo -n "" >> "$commandsFile" ``` The above bash script will create an html file using pandoc, and create a file of neomutt commands. This instructs neomutt to attach the html file, set its disposition, and group the markdown and html files into a "multipart alternatives" group. Neomutt's attachment view should look something like this. ``` I 1 [multipa/alternativ, 7bit, 0K] - I 2 ├─>/tmp/neomutt-hostname-1000-89755-7 [text/plain, 7bit, us-ascii, 0.3K] - I 3 └─>/tmp/neomutt.html [text/html, 7bit, us-ascii, 9.5K] ``` ## Inline attachments The next part of the puzzle is inline attachments. These need to be attached and then grouped within a multipart related group. To reference the file from within the html email, each inline image needs a unique cid. I use md5 sums for this. They are not cryptographically secure, but for the purposes of generating unique strings for images in an email, they are fine. ```bash grep -Eo '!\[[^]]*\]\([^)]+' "$markdownFile" | cut -d '(' -f 2 | grep -Ev '^(cid:|https?://)' | while read file; do id="cid:$(md5sum "$file" | cut -d ' ' -f 1 )" sed -i "s#$file#$id#g" "$markdownFile" done ``` We loop through all the images in the markdown file, and replace the paths for cids (assuming they are not already cids or remote images). As the markdown has changed, we need to attach the new one and detach the old. ```bash if [ "$(grep -Eo '!\[[^]]*\]\([^)]+' "$markdownFile" | grep '^cid:' | wc -l)" -gt 0 ]; then echo -n "\"$markdownFile\"" >> "$commandsFile" fi ``` To attach the images, we loop through the original file and add to the file neomutt sources. Neomutt will be instructed to attach, set the disposition, set the content ID and tag the image. ```bash grep -Eo '!\[[^]]*\]\([^)]+' "${markdownFile}.orig" | cut -d '(' -f 2 | grep -Ev '^(cid:|https?://)' | while read file; do id="$(md5sum "$file" | cut -d ' ' -f 1 )" echo -n "\"$file\"" >> "$commandsFile" echo -n "" >> "$commandsFile" echo -n "^u\"$id\"" >> "$commandsFile" echo -n "" >> "$commandsFile" done ``` ```bash if [ "$(grep -Eo '!\[[^]]*\]\([^)]+' "$markdownFile" | grep '^cid:' | wc -l)" -gt 0 ]; then echo -n "" >> "$commandsFile" fi ``` Finally, if there were any images attached, we select the first entry (the multipart alternative we've already created), tag it and mark everything tagged as multipart related. ``` I 1 [multipa/related, 7bit, 0K] I 2 ├─> [multipa/alternativ, 7bit, 0K] - I 3 │ ├─>/tmp/neomutt-markdown [text/plain, 7bit, us-ascii, 0.3K] - I 4 │ └─>/tmp/neomutt.html [text/html, 7bit, us-ascii, 9.5K] I 5 └─>/tmp/2022-05-27T15-02-20Z.png [image/png, base64, 0.5K] ``` At this point, the user is free to attach additional, non inline documents as normal. This email should be good for both text based and graphical email clients. For the full source changes, see [this commit](https://git.jonathanh.co.uk/jab2870/Dotfiles/commit/08af357f4445e40e98c715faab6bb3b075ec8afa).