Use frm.mailutils to Triage Mailbox Headers from the Shell

You will finish with a repeatable way to list the useful headers in a Mailutils mailbox, add message numbers, select message states, and ask whether unread mail is present. The examples use GNU Mailutils 3.17, installed here as Debian package version 1:3.17-1.1build3.

Allow about fifteen minutes. You need a shell and a mailbox that Mailutils can open. The commands below only read the mailbox. They do not delete, move, send or mark messages as read. If your mailbox contains private mail, avoid pasting its output into a ticket or shell transcript shared with other people.

1. Check the installed command

frm is the short command name, while frm.mailutils is the canonical installed name on this system. Check which binary your shell will run, then record its version:

$ command -v frm.mailutils
/usr/bin/frm.mailutils
$ frm.mailutils --version
frm.mailutils (GNU Mailutils) 3.17

Checkpoint: you should see version 3.17, or you should record the version shown on your own machine before relying on an example. The command's interface is provided by Mailutils, so output details can differ between package versions.

2. Point frm.mailutils at a mailbox

The basic form is frm.mailutils [OPTION...] [URL...]. With no URL, Mailutils resolves its configured default mailbox. That is convenient for daily use, but it can make a test confusing when a user or site configuration points somewhere unexpected.

For a controlled check, pass an explicit mbox URL. This example assumes a test mailbox at /tmp/example.mbox; replace it with a path you are permitted to read:

$ frm.mailutils --no-config 'mbox:/tmp/example.mbox'
Alice Example	First test message
Second Example	Second test message

--no-config prevents site and user configuration files from changing this particular test. It is an ordinary read-only command and does not need elevated privileges. Do not use sudo to work around a mailbox permission problem without first deciding whether the mailbox should be readable by your account.

Checkpoint: if this fails, check the URL spelling and file permissions first. An empty result can mean an empty mailbox, a filter that matched nothing, or a different mailbox format than the one you expected.

3. Make the default listing easier to scan

By default, frm.mailutils prints a compact line for each selected message. The normal display includes the sender and subject. Add -n when you need stable message numbers in notes or a follow-up conversation:

$ frm.mailutils --no-config -n 'mbox:/tmp/example.mbox'
   1:	Alice Example	First test message
   2:	Second Example	Second test message

If the recipient matters, add -l (long option --to). Despite the short option looking unrelated, it means include the To: information:

$ frm.mailutils --no-config -l -n 'mbox:/tmp/example.mbox'
   1:	([email protected])	Alice Example	First test message
   2:	([email protected])	Second Example	Second test message

Use -t or --align when subject lines need tidying. The option changes presentation, not message selection. -Q or --Quiet suppresses the displayed headers, which is useful when a script needs a quiet check but not useful when you are trying to inspect mail.

4. Display a different header field

Use -f NAME to display one header field instead of the normal compact listing. Header names are written without the colon:

$ frm.mailutils --no-config -f Subject 'mbox:/tmp/example.mbox'
First test message
Second test message
$ frm.mailutils --no-config -f Date 'mbox:/tmp/example.mbox'
Wed, 23 Sep 2026 09:00:00 +0100
Wed, 23 Sep 2026 10:00:00 +0100

This is a header display tool, not a body viewer. If a message needs investigation, use a mail client or another Mailutils command designed to inspect its content. Do not infer that a missing field means the message is malformed: not every message has every optional header.

5. Select messages by state

The -s STATUS option limits the messages selected for display. The manpage documents new, unread, old and read; unambiguous abbreviations are accepted. In the installed version, old is treated as another spelling of unread.

$ frm.mailutils --no-config -n -s unread 'mbox:/tmp/example.mbox'
   1:	Alice Example	First test message
   2:	Second Example	Second test message
$ frm.mailutils --no-config -n -s read 'mbox:/tmp/example.mbox'

The exact result depends on the mailbox's message flags. Do not use the output from one mailbox as proof that another mailbox has the same state. If a filter unexpectedly returns nothing, first run the unfiltered command and then inspect how the mailbox format records its flags.

6. Turn unread-mail checking into a shell test

-q or --query prints a message if the mailbox contains unread mail. It is useful in a prompt, status script or monitoring check where you do not need the full header listing:

$ frm.mailutils --no-config -q 'mbox:/tmp/example.mbox'
There are messages in that folder.

For automation, capture both the output and the exit status rather than treating the printed sentence as a Boolean API. The status is the part your shell can branch on:

$ if frm.mailutils --no-config -q 'mbox:/tmp/example.mbox' >/tmp/frm-query.txt; then
>     echo "no unread mail"
> else
>     echo "query reported mail"
> fi
query reported mail

Use a temporary output path with suitable permissions if the query text could contain private information. This example writes only the short query message, but mailbox commands should still be treated as data handling.

7. Check configuration without loading it

Mailutils supports configuration files and can lint a chosen file with --config-lint. This does not repair a file or reload a service:

$ frm.mailutils --config-file /path/to/mailutils.conf --config-lint

Replace the placeholder with a real file path before running it. --config-file implies --no-config, so it gives you a deliberate configuration input rather than a mixture of the chosen file and the normal site and user files. Configuration may contain mailbox locations and other operational details, so avoid making it world-readable while testing.

Most uses do not need elevated privileges. Only use an administrator account when the mailbox or configuration file is intentionally restricted to administrators, and confirm the path before reading it. There is no undo step for the commands in this guide because they make no persistent mailbox changes.