Inspect the Postfix Mail Queue with showq

Mail is stuck somewhere in Postfix, and showq is the queue daemon that can tell you where. You will check which messages are waiting, tell deferred mail from mail already selected for delivery, and pull machine-readable queue data without editing queue files by hand. Allow about 10 minutes. You need Postfix installed and a shell account that can run postqueue; elevated privileges are not normally needed to list the queue.

1. Confirm the installed Postfix version

This guide follows the Ubuntu package installed on the reference system: Postfix 3.8.6. Check your own daemon before relying on version-specific fields or queue ID behaviour.

$ postconf mail_version
mail_version = 3.8.6

If postconf is missing, stop here. Install or repair the Postfix package through your distribution's normal package process. Do not create a queue directory by hand.

2. List the queue through the supported client

showq(8) is the daemon that reports queue status, but you never talk to it directly for a routine look. Its output is meant to be formatted by postqueue(1), which is the command to use for an ordinary inspection.

$ postqueue -p
-Queue ID-  --Size-- ----Arrival Time---- -Sender/Recipient-------
72D6CD1C0583    5222 Thu Sep 24 14:01:07  MAILER-DAEMON
                                         [email protected]

-- 5 Kbytes in 1 Request.

Your IDs, dates and recipients will differ. A queue count of zero is a valid result. The listing can change while it is being produced, so treat it as a point-in-time view rather than a transactionally consistent snapshot. Here is what each part of that output tells you:

• Queue ID: identifies the message for later administrative work, such as holding or tracing it.
• Size and arrival time: describe the queued message itself.
• Sender and recipients: the envelope addresses still awaiting delivery.
• Reason line: a line under a recipient normally explains the last failed delivery attempt.
• Asterisk after the queue ID: marks the active queue, where the message is selected for delivery right now.
• Exclamation mark: marks the hold queue, where delivery is paused.

A visible queue entry is not proof that delivery will fail. A message may be in active processing, and another process can remove or alter an entry immediately after the listing runs.

3. Produce JSON Lines for a script

For monitoring or a one-off count, use postqueue -j. Postfix emits one JSON object per queue file, one object per line. This option has been available since Postfix 3.1, so it is present in 3.8.6.

$ postqueue -j | head -n 1
{"queue_name":"deferred","queue_id":"72D6CD1C0583","arrival_time":1727186467,"message_size":5222,"sender":"MAILER-DAEMON","recipients":[{"address":"[email protected]","delay_reason":"temporary failure"}]}

Fields can grow over time, so a consumer should ignore members it does not recognise. The queue can change during the scan too, so a message may be missed or appear more than once. Use a JSON parser in a script rather than splitting the traditional display on spaces.

$ postqueue -j | jq -r 'select(.queue_name == "deferred") | [.queue_id, .sender] | @tsv'
72D6CD1C0583	MAILER-DAEMON

jq is optional and must already be installed. If it is absent, keep the raw JSON or use the parser already approved for your monitoring host.

4. Check configuration changes without touching the queue

The daemon reads relevant main.cf settings when its short-lived processes start. After changing a setting that affects queue display, ask Postfix to reload so new processes pick it up quickly.

$ sudo postfix reload
postfix/postfix-script: refreshing the Postfix mail system
$ postqueue -p

postfix reload changes service state, so use sudo and schedule it like any other service operation. It does not flush, delete or requeue messages. If the reload reports an error, inspect the Postfix log rather than repeatedly retrying.

5. Recover visibility when Postfix is down

showq can run in standalone mode as the superuser, which is useful when the Postfix mail system itself is stopped. Treat this as an emergency inspection path, not a replacement for postqueue. Resolve the daemon directory from the live configuration rather than assuming a hard-coded installation path.

$ sudo "$(postconf -h daemon_directory)/showq"
$ printf 'showq exit status: %s\n' "$?"

The normal daemon interface is built for Postfix's own clients, so direct output and exit status here are not a stable scripting interface. If this command fails, check the system log for showq, postlogd or syslogd messages and confirm that the queue directory from postconf queue_directory is present. Do not run it as an unprivileged user and do not modify files under the queue directory by hand.

Common traps

• Using showq as a user-facing filter: it is a daemon, not a queue-management command. Start with postqueue -p or postqueue -j.
• Confusing listing with delivery: neither listing command sends mail. Queue flushing and message deletion are separate operations with their own safety risks.
• Assuming IDs are globally unique: queue IDs can be reused by a Postfix instance. Include the host when storing them in external records.
• Expecting a static answer: queue contents change while delivery workers run. Record the command time alongside monitoring results.
• Ignoring local exposure: the showq service port is accessible to local untrusted users and can be susceptible to denial-of-service attacks. Keep the service protected by the Postfix service configuration and investigate unexpected local load.