Decode MIME Mailboxes to UTF-8 with decodemail

A mailbox full of base64 and quoted-printable is no use to grep, and decodemail turns it into readable text in one command. This guide ends with a decoded output mailbox and a repeatable way to recode text as UTF-8 without destroying an existing result. The examples use GNU Mailutils decodemail 3.17, installed here from package version 1:3.17-1.1build3.

Allow about ten minutes.

• You need: a readable input mailbox, a writable destination, and the Mailutils package.
• It will not: send anything. The command reads and transforms mail only.
• Safest start: work on a copy first if the mailbox contains anything you may need to preserve.

1. Check the installed command

Confirm which program will run and record its version:

$ command -v decodemail
/usr/bin/decodemail
$ decodemail --version
decodemail (GNU Mailutils) 3.17

The exact copyright and licence lines may vary, but the version should identify the installed Mailutils release. The local manpage describes the positional arguments as INBOX and OUTBOX. They are source and destination mailboxes, not email addresses.

2. Decode a mailbox into a new file

Choose a destination that does not already contain useful mail, then pass the input and output paths:

$ decodemail --no-config /path/to/inbox.mbox /path/to/decoded.mbox
$ printf 'exit status: %s\n' "$?"
exit status: 0

--no-config keeps site and user configuration files out of this first test, so the command line is the whole story. Once the result is understood, you can drop that option if your Mailutils configuration is part of the intended workflow.

What it does: GNU describes decodemail as a mailbox conversion tool. Text parts of multipart messages are decoded to plain text, while non-multipart messages and parts that cannot be decoded are transferred verbatim. Message headers and mailbox bookkeeping can therefore differ from the input even when the message content is unchanged.

Verify that the destination exists and is non-empty without opening it in a mail client:

$ test -s /path/to/decoded.mbox && echo 'output mailbox is non-empty'
output mailbox is non-empty
$ grep -c '^Subject:' /path/to/decoded.mbox
1

3. Recode text parts as UTF-8

Decoding a transfer encoding and changing a character set are separate jobs. For a predictable UTF-8 result, request the output charset and enable recoding:

$ decodemail --no-config --recode --charset=UTF-8 \
    /path/to/inbox.mbox /path/to/decoded-utf8.mbox
$ printf 'exit status: %s\n' "$?"
exit status: 0

• --recode, also written -R, recodes text parts to the current charset.
• --charset=UTF-8, also written -c UTF-8, selects the output charset.

Supplying both makes the intention clear in a script and leaves decoded text parts labelled as UTF-8.

Inspect the headers and a small amount of text:

$ sed -n '1,35p' /path/to/decoded-utf8.mbox
$ file -b /path/to/decoded-utf8.mbox
ASCII text

4. Decide what happens to an existing output

$ cp --preserve=all /path/to/decoded.mbox /path/to/decoded.mbox.bak
$ decodemail --no-config --truncate \
    /path/to/inbox.mbox /path/to/decoded.mbox
$ printf 'exit status: %s\n' "$?"
exit status: 0

$ mv /path/to/decoded.mbox.bak /path/to/decoded.mbox

When the destination should accumulate another run, use --no-truncate. The installed command appends converted messages to an existing mailbox in that mode. Appending can create duplicates if you process the same input twice, so use a fresh destination for repeatable jobs or track which input has already been handled.

5. Control configuration and privileges

Mailutils tools can read site and user configuration. Use --no-config for an isolated conversion, or choose an explicit file with --config-file=/path/to/mailutils.conf. That option implies --no-config. Before relying on a configuration file, ask the program to lint it:

$ decodemail --no-config --config-file=/path/to/mailutils.conf --config-lint
$ printf 'exit status: %s\n' "$?"
exit status: 0

This checks syntax and exits; it does not convert a mailbox. If you only want to see the available configuration settings, use --config-help or --show-config-options. Do not put passwords into a command copied into shell history or a shared script.

6. Diagnose the likely failures

If the command cannot open the input, check the path and permissions without changing anything:

$ ls -l /path/to/inbox.mbox
$ test -r /path/to/inbox.mbox && echo readable
$ test -w /path/to && echo destination-directory-writable

• Output empty or unchanged. Confirm that you supplied the intended input and that the destination is not the same file. Keep the input and output paths distinct while testing.
• MIME text still encoded. Inspect the message's content type and transfer encoding, then try the explicit --recode --charset=UTF-8 form.
• Some parts untouched. Parts that Mailutils cannot decode are intentionally copied verbatim rather than guessed at.

For option details or a short syntax reminder, run:

$ decodemail --help
$ decodemail --usage

These options include debugging and configuration controls, but they do not turn decodemail into a mail sender or a message editor. Keep destructive output replacement, credentials, and service changes outside a blind batch command.