Demo
Demo

Knowledge base

PMTA knowledge base›API endpoint§ 5.4

Queues with the most recipients

/queues
The top, not the whole list

Returns queues — “receiver and sending address” pairs — with counters: the same as the monitor’s “Top queues” page, only as a structure.

The call is GET /queues?format=json (or xml). The queue parameter narrows the selection with a “domain/address” pair, and either half can be a star: queue=*/vmta1 means the queues of one sending address. The manual has no separate endpoint for a sending address — its details are described exactly this way.

This is the top, not a list. How many lines arrive is decided by http-default-max-items — ten by default — and the order by http-default-sort-order, by number of recipients by default.

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 taking the top for the whole list. On a node with a hundred queues the default response carries ten: whoever counts “how many queues are in backoff mode” or “how many are paused” by lines gets a number only for the top ones. The show queues command has its own ceiling — twenty lines — so the full list there is taken with –maxitems too.

And it is a snapshot: a queue that was in backoff mode between two requests will not make it into the response.

What the Hub does. It asks twice. The node poll takes /queues?format=json&maxItems=1 every minute together with /status — telemetry needs only the total, and the total does not depend on the length. The “PMTA monitoring” screen takes the endpoint together with /domains, /vmtas and /jobs and passes the length maxItems=1000.

The screen takes the number of queues with messages from the totalQueuesWithRcp total rather than counting lines; if exactly a thousand lines arrived, the screen says the list is cut. The Hub asks separately about paused queues and queues in backoff mode with commands through /command — with –maxitems=10000.

Recommended values

What to ask this endpoint:

Question This one or not
which queues are the largest right now yes
the queues of one sending address yes — queue=*/address, but also as a top
all node queues without exception no — show queues with –maxitems
the history of one queue no — /queueDetail
what happened yesterday no — that is accounting
The queue parameter with stars, the “Top queues” page, the list length and order, and the command’s ceiling of twenty queues come from the manual (§ 5.4, § 5.9, § 3.3.1.58.23–24, § 6.3.14). The split of questions and the conclusion about counting by lines are ours.
Example configuration
# the top queues and the queues of one sending address
curl -s 'http://127.0.0.1:8080/queues?format=json'curl -s 'http://127.0.0.1:8080/queues?format=json&queue=*/vmta1'
The second line narrows the selection to one sending address — that is how the manual describes its details. The response length in both cases is http-default-max-items.
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

Depends on

A queue is a receiving server together with a sending addressThe mechanism that is visible here. § 5.9

Can be replaced by

QueuesThe screen that shows the same thing to a human. § 5.4

Referenced from

Sending addresses that have a queueA neighboring catalog entry. § 5.9

How to check on the node
Compare how many queues arrived with how many the node has:
curl -s 'http://127.0.0.1:8080/queues?format=json' | head -60
pmta show queues --maxitems=1000 --no-rcpt-events
If the console lists more queues than arrived in the response, that is the top by http-default-max-items, not a data mismatch.
◇

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.◇Two inbound report processors and what to do with themBounces by message and complaints are parsed by two identically structured blocks; each has its own address list and its own pair of decisions about the message’s fate.◇Five ways for a queue to hand off a messageA queue does not have to use SMTP: it can write to a file, run a program, call over HTTP or discard.

In the Hub
Cost of a mistake
safe: a wrong value breaks nothing
Scenarios
Collect telemetry