Count Mailbox Messages Reliably with messages.mailutils

You will finish with a repeatable way to count messages in a local mailbox, use the numeric result in a shell script, and tell a missing mailbox from a successful count. The examples use GNU Mailutils 3.17, installed here as Debian package version 1:3.17-1.1build3.

Allow about ten minutes. You need a shell, the mailutils package, and read access to the mailbox you want to inspect. The normal examples are unprivileged. Do not use sudo unless the mailbox permissions genuinely require it.

1. Confirm the installed command

Check the binary and version before relying on its output. These are read-only commands:

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

The package also installs messages as an alias. Use the longer name in scripts when you want the provider to be obvious, especially on a host that may have another command with a similar name.

2. Count an explicit mailbox

The command accepts one or more mailbox arguments. An ordinary local mbox file is a useful first test. Replace the path with the mailbox you actually intend to inspect:

$ messages.mailutils /var/mail/ACCOUNT
Number of messages in /var/mail/ACCOUNT: 12

The number and path in the output are examples. The command reads the mailbox and reports the count; it does not display message bodies. If your system keeps mail somewhere else, pass that location explicitly rather than guessing from another machine's layout.

For a personal mailbox, you may need to use a path inside your home directory. Reading a mailbox can still expose private mail to anyone who can see your terminal or process output, so avoid putting the result or path into a shared log without checking your local privacy requirements.

3. Request output that is safe to capture

Use --quiet, or its short form -q, when another command needs only the number:

$ messages.mailutils --quiet /var/mail/ACCOUNT
12
$ messages.mailutils -q /var/mail/ACCOUNT
12

Both forms select the documented quiet mode. It prints only the message count on a successful run, which avoids having to strip the descriptive prefix from normal output.

For a shell decision, test the exit status separately from the count. Capture standard output first, then check whether the command succeeded:

count=$(messages.mailutils --quiet /var/mail/ACCOUNT)
status=$?
if [ "$status" -ne 0 ]; then
    printf 'Could not count /var/mail/ACCOUNT (status %s)\n' "$status" >&2
    exit "$status"
fi
printf 'messages=%s\n' "$count"

4. Keep configuration behaviour explicit

Mailutils has configuration controls in this command's interface. Site and user configuration files are loaded by default unless you disable them. For a predictable diagnostic against a named mailbox, add --no-config:

$ messages.mailutils --no-config --quiet /path/to/mailbox
12

This option prevents site and user configuration files from being loaded. It is useful when a count works on one host but fails on another, or when you are testing a path and want configuration differences out of the investigation. It does not bypass filesystem permissions and does not repair a malformed mailbox.

If you need one known configuration file, use --config-file. The manual states that this implies --no-config, so the selected file is not combined with the usual site and user files:

$ messages.mailutils --config-file /path/to/mailutils.conf --quiet /path/to/mailbox
12

Do not invent configuration parameter names. The command also offers --config-lint to check a configuration file's syntax and exit. Run it against the configuration file itself, not against a mailbox:

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

A non-zero result means the file was not accepted. Read the diagnostic, correct the configuration through your normal change process, and rerun the lint check. This is a configuration change workflow, so keep a backup or version-controlled copy before editing. Do not overwrite a working system file as a quick experiment.

5. Diagnose the common failure

A missing or unreadable mailbox is a failed count, not zero messages. Test with a deliberately wrong path only when you are checking error handling:

$ messages.mailutils --no-config --quiet /path/to/missing-mailbox
messages.mailutils: could not open mailbox `/path/to/missing-mailbox': No such file or directory
$ printf 'status: %s\n' "$?"
status: 1

The exact error text depends on the path and operating system. The important checks are the non-zero status and the reported path. Check the path without changing anything:

$ ls -l /var/mail/ACCOUNT
$ test -r /var/mail/ACCOUNT && printf '%s\n' 'mailbox is readable'

If the file exists but is not readable, ask its owner or administrator to fix access through the host's normal mail administration process. Avoid broad permission changes on a mailbox: mail is sensitive data, and making it world-readable to make one command work is a security problem.

6. Avoid misleading checks

Do not parse normal output with a fixed string such as Number of messages in when quiet mode is available. Do not treat an empty or missing result as an empty mailbox. A successful zero count is different from an error opening the mailbox, and the exit status preserves that distinction.

Do not assume that --config-lint validates a mailbox. It validates the configuration file selected by --config-file. Likewise, --config-verbose reports configuration parsing; it is a diagnostic option, not a replacement for checking the mailbox path and permissions.

When testing a script, use a disposable test mailbox or a copy that contains no private mail. Keep the production mailbox untouched. If you need to remove a temporary test file, confirm its exact path first and use your normal recoverable deletion process; nothing in this guide requires deleting mail.