Demo
Demo

Knowledge base

PMTA knowledge base›Command§ 6.3.14

show queues

critical

Queue state together with event history
The most informative read command — with events included by default

Prints the state of queues: how many recipients are waiting, how many kilobytes, how many connections are open, what mode the queue is in. A queue here is a “receiving server plus sending address” pair (queue-identity), so one domain from three addresses gives three lines.

Events are included by default. Along with the queues, the command prints the last fifty deliveries, bounces and delays. The manual says so directly and provides an option to hide them — and if there is a “hide” option, they are there by default.

A separate option adds the history of mode changes — the very transitions into backoff mode and back that otherwise have to be reconstructed by polling: comparing the queue’s mode with what it was last time.

The selectors are the working vocabulary of an investigation. By open connection, by mode, by pause state. The last one distinguishes what is easy to confuse: a queue stopped by an operator and a queue held back by the node itself.

Sorting — by name, by number of recipients or by volume; twenty queues are printed by default.

The main trap is the default of twenty queues. On a node with hundreds of queues, the command without an option shows twenty and gives no hint that the rest exist. The output looks complete and is not. The same question about the whole node has to be asked with an explicit number, and preferably with sorting — otherwise the twenty lines will be random.

And the second one is a domain name without a sending address. show queues gmail.com shows one queue, gmail.com/{default}, not all queues of this receiver; all of them are gmail.com/* (verified on a node on Sep 15, 2026: of the domain’s three queues the command showed one empty one).

What the Hub does. It calls it through POST /command with the node key: every five minutes show queues –mode=backoff — that is how it assembles backoff episodes — and show queues –paused=yes for the control snapshot. It passes the length explicitly, –maxitems=10000: without it the selection would be cut at twenty queues, and episodes would open and close depending on what made it into the top. A selection that reached this length is considered incomplete by the Hub, and episodes are not closed by it. The queue list for the “PMTA monitoring” screen and telemetry comes from the /queues request.

The Hub reconstructs the history of mode changes by polling — it compares the selection with the previous one. The –mode-events option would give it at once and more precisely: polling is blind between two rounds and misses a short trip into backoff mode.

Recommended values

Options worth having at hand:

Task How to call it
see everything, not twenty with an explicit number and sorting by recipients
find what is stuck select by mode to see only backoff queues
separate what an operator stopped select by pause state
understand when a queue went into backoff mode the mode change history option
remove the noise of events the option that hides recipient events

Start with sorting by recipients. The twenty largest queues answer most questions; twenty random ones answer none.

Selecting by pause state is the first thing worth checking when a queue “is not sending”: stopped by an operator and held back by the node look the same but are treated differently.

The investigation order and the advice on options are ours. From the manual here are the composition of the output, the default of twenty queues, events being on by default and the full set of selectors.
Example configuration
# the twenty largest queues with mode change history
pmta show queues --maxitems=20 --sort=rcpt --mode-events# only those in backoff mode, without the noise of events
pmta show queues --mode=backoff --no-rcpt-events
The highlighted line answers the question “what is on the node right now”: the largest queues and when each changed mode. The bottom one answers “what is being held back.”
yellow — — directive names, blue — blocks. They are highlighted the same way in the text of the card.
▲

Common mistakes and problems

what people get wrong and how it ends3 mistakes▶

Taking twenty lines for the whole node

§ 6.3.14

What it costsBy default twenty queues are printed, and the output gives no hint that there are others. The question “what is going on on the node” gets an answer based on a random twenty.
How to spot itThe investigation runs into the problematic queue not being in the output, even though messages for it are piling up.
How to do it rightCall it with an explicit number and sorting by recipients — then the twenty lines will be the twenty largest.

Confusing a paused queue with one held back by the node

§ 6.3.14

What it costsA queue stopped by an operator and a queue that went into backoff mode look similar in the general output, but their causes and treatment differ. Time is spent analyzing receiving server refusals where the queue was simply stopped by hand.
How to spot itThe queue is not sending, and there are no receiving server refusals in the log.
How to do it rightSelect by pause state — it is the first thing worth checking when a queue is silent.

Reconstructing mode history by polling

§ 6.3.14

What it costsPolling is blind between two measurements: a queue that managed to enter and leave backoff mode will not get into the history at all. The command has an option that returns the transitions directly.
How to spot itThe transition history is empty, yet there were receiving server refusals.
How to do it rightAsk for the history with the option rather than deriving it from the difference between measurements.
Compatibility
PowerMTA 6.0
described in the manual of this version · platform: any
The vendor does not state the first version for every directive — there is no note here. The name also appears in the 5.0 edition of the manual.
⇄

Related entries

5 relations

Depends on

How to name a queue in a commandHow to name a queue in the argument: the same pair with asterisks. § 6.3.14Recipient eventsThe very delivery and bounce events that are printed by default. § 11.17

Same name in other blocks

The busiest queuesThe same command with sorting — the manual calls them equivalent. § 6.3.19

Can be replaced by

Three short histories for each queueThe same view for a single queue on the monitor screen — with the histories. § 5.4

Where you can see it

Backoff mode — the queue's second personalityPrints both the current mode of each queue and, with an option, recent transitions between modes. § 6.3.14

Referenced from

What the node tells about itself and through which channelsThe same question from the console — and in machine formats, not just on screen. § 1.4track-recipient-events<domain>The command that prints these events; the –no-rcpt-events option hides them. § 6.3.14QueuesThe same output from the command line. § 5.4Change a queue's mode by handA neighboring command: the same subject from another side. § 6.3.14Removing a sending address — and what happens to its queueThe check before removal: are there still messages tied to this sending address. inference

How to check on the node
The command itself is the check. It is worth comparing with two other views:
pmta show queues --sort=rcpt --maxitems=50
pmta show domains
pmta show settings gmail.com/mta-news-1
The first gives a line per queue, the second adds addresses together and gives a line per domain: the numbers will not match, and that is not an error. The third shows which limits apply to a specific queue from the first.
◇

What else to read

3 articles

◇What the node tells about itself and through which channelsSeven observation surfaces: the web monitor, the console in four formats, the log, accounting, accounting search, metrics and export to external analytics.◇The watchdog that restarts the engineKeeps an eye on the engine and brings it back up after a crash by itself, sending a crash report to the postmaster address.◇How the policy for a receiver is assembledSettings are assembled from the most general pattern to the most precise; the order of blocks in the file means nothing.

In the Hub
Cost of a mistake
safe: a wrong value breaks nothing
Scenarios
Troubleshoot deliverability · Tune the pace for a provider · Untangle a stuck queue
Priority
critical