Demo
Demo

Knowledge base

PMTA knowledge base›API endpoint§ 5.13

Messages in the queue

/listqueue
Who exactly is waiting

Lists the messages that are in the queue right now — with filtering.

The call is GET /listqueue?format=json&queue=domain/address. Either half of the pair can be a star. Optional parameters narrow the selection: jobid — the job, envid — the envelope identifier, rcpt — the recipient, orig — the sender.

It answers a question no counter will: where a specific message is and what is still waiting to be sent to a specific person. queue=*/* with rcpt searches for a recipient across the whole node.

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 a */* selection without a filter. The endpoint lists messages one by one, and on a node with a large queue such a request returns a response as large as the queue itself. Filtering by recipient, sender or job keeps the response short.
What the Hub does. It does not ask: the Hub does not show messages one by one, and it deletes a queue and changes its mode with commands through /command.
Recommended values

What to ask this endpoint:

Question This one or not
where a specific message is yes — the rcpt or orig filter
what is still waiting for one campaign yes — the jobid filter
how many messages are in the queue no — /queues
what happened yesterday no — that is accounting
The queue, jobid, envid, rcpt, orig parameters and stars come from the manual (§ 5.13). The split of questions and the filtering advice are ours.
Example configuration
# all messages to one recipient across the whole node
curl -s 'http://127.0.0.1:8080/listqueue?format=json&queue=*/*&rcpt=user@example.com'curl -s 'http://127.0.0.1:8080/listqueue?format=json&queue=gmail.com/vmta1&jobid=12'
The first line searches for a recipient in all node queues, the second for one job’s messages in one queue.
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.13

Works together with

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

Referenced from

How to name a queue in a commandA request that returns the same thing. § 5.13The list of recipients in a queueThe same thing, returned by a request. § 5.13

How to check on the node
Compare the response with the console:
curl -s 'http://127.0.0.1:8080/listqueue?format=json&queue=*/*&rcpt=user@example.com' | head -40
pmta list --rcpt=user@example.com
The command has its own ceiling — a hundred recipients by default, and –maxitems shows more. If the console sees the message but the request does not, check the requesting address’s permissions in http-access.
◇

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.◇A license for a fleet, not for a serverThe license is not bound to a server: it is installed on as many machines as the instance limit allows, and the nodes send volume statistics to the vendor every hour.◇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.

In the Hub
Cost of a mistake
safe: a wrong value breaks nothing
Scenarios
Untangle a stuck queue · Sender isolation