Demo
Demo

Knowledge base

PMTA knowledge base›API endpoint§ 5.4

Details of one queue

critical

/queueDetail
Three short histories

Returns one queue with its short histories — the same as the queue page in the monitor: the last 50 recipient events, the last 10 queue errors and the last 10 changes between normal and backoff mode.

The call is GET /queueDetail?format=json&queue=domain/address. The manual shows no stars for this endpoint: it describes one queue, and /queues gives selections.

The histories are rolling: the eleventh mode change pushes out the first. On a busy queue fifty recipient events are the last few minutes, so for an older case go to accounting.

Access is decided by http-access based on the address the request came from — the monitor level is enough for reading. The key from http-api-key in the X-API-Key header grants full access from any address.

The main trap is looking for old history here. The histories are short: fifty events and ten each of errors and mode changes. What happened this morning on a loaded queue is no longer visible here — that is a question for accounting.
What the Hub does. It does not ask. It reconstructs mode changes itself: every five minutes it asks the node with a command through /command which queues are in backoff mode now, and builds episodes from a queue appearing in and disappearing from that list. A short trip between two rounds is lost that way — while here it would be visible.
Recommended values

What to ask this endpoint:

Question This one or not
why this particular queue is stuck yes — the latest errors
when the queue went into backoff mode yes, within the last ten changes
which queues are large no — /queues
what happened yesterday no — that is accounting
The layout of the histories and the form of the queue parameter come from the manual (§ 5.4). The conclusions about history depth and the split of questions are ours.
Example configuration
# one queue with its histories
curl -s 'http://127.0.0.1:8080/queueDetail?format=json&queue=gmail.com/vmta1'
The pair is written in full: the recipient domain and the sending address name. /queues gives a selection with stars.
yellow — — directive names, blue — blocks. They are highlighted the same way in the text of the card.
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

2 relations

Can be replaced by

Three short histories for each queueThe screen that shows the same thing to a human. § 5.4

Where you can see it

Backoff mode — the queue's second personalityThe mechanism that is visible here. § 5.4

How to check on the node
Compare the response with the console:
curl -s 'http://127.0.0.1:8080/queueDetail?format=json&queue=gmail.com/vmta1' | head -60
pmta show queues --mode-events gmail.com/vmta1
If the console sees the queue but the request does not, check how the pair is written: the sending address name must match the configuration.
◇

What else to read

3 articles

◇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.◇Backoff mode — the queue's second personalityA queue that a receiver has started refusing switches to a parallel set of limits, retries and routes — ten directives that act only in this mode.◇Reputation monitoring inside the nodeThe engine itself watches the receiving servers’ replies and changes the queue mode on a pattern match — a reaction within the connection, not through telemetry.

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