Count Mailbox Messages Reliably with messages.mailutils

A cron job needs to know how many messages sit in a mailbox, and messages.mailutils gives you that count without opening a single message. 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; don't use sudo unless the mailbox permissions genuinely require it.

1. Confirm the installed command

Check the binary and version before trusting 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 might 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 above are examples. The command reads the mailbox and reports the count; it does not display message bodies. If your system keeps mail elsewhere, pass that location explicitly rather than guessing from another machine's layout.

For a personal mailbox you may need 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 dropping the result or path into a shared log without checking your own privacy requirements first.

3. Request output that is safe to capture

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

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

Both forms select the documented quiet mode, printing only the message count on a successful run, which saves you from stripping the descriptive prefix off normal output.

For a shell decision, test the exit status separately from the count. Capture standard output first, then check whether the command actually 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 baked into this command's interface. Site and user configuration files load 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 stops site and user configuration files from loading at all. It's useful when a count works on one host but fails on another, or when you're 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 never combined with the usual site and user files:

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

Don't 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 rejected. Read the diagnostic, fix 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: don't 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're 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. What matters is 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 isn't 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 just to get one command working is a security problem.

6. Avoid misleading checks

• Don't parse the descriptive text. Number of messages in is fragile string-matching when quiet mode already exists.
• Don't treat an empty result as an empty mailbox. A successful zero count is different from a failed open, and the exit status is what preserves that distinction.
• Don't assume --config-lint validates a mailbox. It validates the configuration file selected by --config-file, nothing else.
• Don't treat --config-verbose as a mailbox check. It reports configuration parsing, and is a diagnostic option, not a substitute for checking the mailbox path and permissions.

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