Read Mailbox Messages Precisely with readmsg.mailutils

You will use readmsg.mailutils to print selected messages from a mailbox, control how much header information appears, and make repeated matches explicit. The command is also available as readmsg on systems that provide that alias.

Allow about 10 minutes for a first pass. You need GNU Mailutils installed and read access to the mailbox you want to inspect. The examples use a placeholder mailbox path, so replace it before running them. Reading a mailbox does not require elevated privileges unless its file permissions require them; use the least privilege that can read the file.

1. Check the installed command

This guide was checked with GNU Mailutils 3.17, from the Debian package version 1:3.17-1.1build3. Confirm the version and review the options available on your own host:

readmsg.mailutils --version
readmsg.mailutils --help

The installed manpage calls the program a message printer. It does not describe a mailbox as a file you should modify, and the command has no option for deleting or moving messages. Treat its output as a read operation, while still protecting sensitive message contents in terminals, logs and copied command output.

2. Select a mailbox and a message

Use --folder or its short form -f to select a mailbox explicitly:

readmsg.mailutils --folder=/path/to/mailbox 'Weekly report'

The selection text is positional. With the default --exact mode, Mailutils searches for an exact string and prints the first matching message. Put the selection in single quotes when it contains spaces or shell characters. Quoting protects the search text from the shell; it does not change Mailutils' matching rules.

A mailbox path is data, not a command. Do not paste an untrusted path into a shell expression containing substitutions or redirections. Keep the path as the value of --folder and inspect it before running the command.

When you need every matching message, add --show-all-match, or -a:

readmsg.mailutils --folder=/path/to/mailbox --show-all-match 'Weekly report'

Without that option, a repeated subject or body match can look like a complete result while silently stopping after the first message. That default is useful for a quick lookup but unsafe for an audit or export where completeness matters.

3. Choose the matching mode deliberately

The default is exact matching. The installed command also supports shell-style globbing and POSIX regular expressions:

# A shell-style pattern
readmsg.mailutils --folder=/path/to/mailbox --glob --show-all-match 'Weekly*'

# A POSIX regular expression
readmsg.mailutils --folder=/path/to/mailbox --regex --show-all-match 'Weekly (report|digest)'

Use --ignorecase when letter case should not distinguish messages:

readmsg.mailutils --folder=/path/to/mailbox --ignorecase 'weekly report'

Globbing and regular expressions are different languages. Do not write a regular expression and assume that --glob will interpret it correctly. If a pattern becomes difficult to review, first test it against a copy of representative mail and keep --show-all-match enabled so the result is visible.

4. Control headers and message content

By default, output includes the normal selected headers. Use --header or -h to display the entire header, including fields normally omitted. Use --no-header or -n when a body-only result is easier to process:

# Show every header field
readmsg.mailutils --folder=/path/to/mailbox --header 'Incident 4821'

# Omit all headers
readmsg.mailutils --folder=/path/to/mailbox --no-header 'Incident 4821'

These options describe what is printed, not what is matched. Header fields can still be relevant to a selection even when they are hidden from the output. For a compact, reviewable result, use --no-header only after you have confirmed that the selected body is the data you want.

Use --mime to decode MIME messages on output:

readmsg.mailutils --folder=/path/to/mailbox --mime 'Invoice attached'

Decoded output can be much larger or less visually recognisable than the stored message. Redirect it only to a destination with suitable permissions, and remember that attachments or encoded content may contain secrets or active files. Do not execute anything merely because it was printed by this command.

For multiple messages, --form-feeds places form-feed characters between messages. This can help a pager or a printer separate records, but it may confuse line-oriented tools. Leave it off when another program expects ordinary text lines.

5. Make scripts predictable

For a script, specify the mailbox, matching mode and header policy rather than relying on a user's configuration or the command's defaults:

readmsg.mailutils \
  --no-config \
  --folder=/var/mail/example \
  --exact \
  --show-all-match \
  --no-header \
  'Build finished'

--no-config prevents site and user configuration files from being loaded. This reduces surprises when the same script runs under different accounts. If you intentionally need a particular configuration, use --config-file=/path/to/mailutils.conf; the manpage says that this also implies --no-config.

Do not add --debug to normal output pipelines. It is for diagnostic information and can expose mailbox details or make machine-readable output unusable. When diagnosing a failure, run it separately and capture the result only where the message data is safe.

Configuration can also be checked without printing messages:

readmsg.mailutils --config-lint --config-file=/path/to/mailutils.conf

The lint command checks configuration syntax and exits. It does not prove that the mailbox exists, that the account can read it, or that a selection will match.

Common failure points

• No output: verify the exact mailbox path and test a distinctive phrase. Also check permissions with stat /path/to/mailbox; use elevated privileges only if your mailbox policy requires them.
• Only one result: the default is to print the first match. Add --show-all-match when completeness matters.
• Unexpected case behaviour: exact matching is case-sensitive unless you add --ignorecase.
• Unreadable output: MIME decoding changes presentation. Compare the same selection without --mime before deciding that the stored message is damaged.
• Script output changes between hosts: configuration files may differ. Add --no-config and make the important options explicit.