Demo
Demo

Knowledge base

PMTA knowledge base›API endpoint§ 5.5

Receivers with the largest queue

/domains
Addresses summed, list truncated

Returns recipient domains, summing all sending addresses for each: the number of recipients, volume, open connections and the last delivery error.

The call is GET /domains?format=json (or xml). Details of one domain come from a separate endpoint, /domainDetail.

This is the “Top domains” top: the length is set by http-default-max-items, ten lines by default, and the order by http-default-sort-order.

The numbers will not match the sum over /queues, and that is not an error: there the same mail is split into pairs, and the two tops cut off different things.

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 counting by lines. The default response carries ten domains: “how many receivers have errors” or “how many domains are in the queue”, counted by lines, describe only the top of the list. The show domains command truncates too — twenty lines by default — so the full list is taken with –maxitems.
What the Hub does. It asks — the “PMTA monitoring” screen takes this endpoint together with /status, /queues, /vmtas and /jobs and passes the length maxItems=1000. The screen takes the number of queued domains from the totalDomainsWithRcp total; if exactly a thousand lines arrived, a note under the list says it is cut. The telemetry poll does not take this endpoint.
Recommended values

What to ask this endpoint:

Question This one or not
which receivers get the most mail yes
where delivery errors are now yes, but only among the top ones
all domains in the queue no — show domains with –maxitems
what happened yesterday no — that is accounting
The line contents, the “Top domains” page, the list length and order, and the command’s ceiling of twenty domains come from the manual (§ 5.5, § 3.3.1.58.23–24, § 6.3.13). The split of questions is ours.
Example configuration
# top receivers as a structure
curl -s 'http://127.0.0.1:8080/domains?format=json'
The response has as many lines as http-default-max-items sets; ten by default.
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

1 relation

Can be replaced by

Receivers summed across all sending addressesThe screen that shows the same thing to a human. § 5.5

How to check on the node
Compare the top with the full list:
curl -s 'http://127.0.0.1:8080/domains?format=json' | head -60
pmta show domains --maxitems=1000
The console with a large –maxitems lists all domains in the queue; the difference in the number of lines is the length of the top, not data loss.
◇

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