Demo
Demo

Knowledge base

PMTA knowledge base›API endpoint§ 5.2

Web monitor root

monitor base URL
The entry point

Returns the monitor’s start page as a structure: installation information and a table of the domains with the largest queue.

The call is GET /?format=json (or xml). Without the parameter, the root redirects to the human page /ui, and only the address without that suffix returns the structure.

The domain table here is a top, not a list: the length is set by http-default-max-items, ten lines by default.

Port and scheme. The monitor listens on http-mgmt-port, 8080 by default. With the http-redirect-to-https default, a request over http is redirected to https, so it is simpler for a script to go over https straight away — with a self-signed certificate if you did not install your own.

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 an address with /ui. The monitor link is usually copied from the browser, where /ui is already present: such a request returns the human page, and parsing the response breaks on the first character. The structure comes only from the root with the format parameter.
What the Hub does. It does not ask: the per-minute node poll takes /status and /queues, and the “PMTA monitoring” screen also takes /domains, /vmtas and /jobs. The root remains a manual tool.
Recommended values

What to ask this endpoint:

Question This one or not
what installation this is and which domains lead the queue yes
the full node state no — that is /status
all domains in the queue no — /domains also returns a top of the same length
what happened yesterday no — that is accounting
The address without /ui, the format parameter, the domain table length, the port and the redirect to https come from the manual (§ 5.1, § 5.2, § 3.3.1.58.1–2, § 3.3.1.58.23). The split of questions is ours.
Example configuration
# the monitor root as a structure: without the /ui suffix
curl -s 'http://127.0.0.1:8080/?format=json'
Port 8080 is the http-mgmt-port default. With the /ui suffix the same address would return the human page.
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

The whole node state in one documentA neighboring catalog entry. § 5.3

How to check on the node
Check that the root answers with a structure, not a page:
curl -s -o /dev/null -w "%{http_code} %{content_type}\n" 'http://127.0.0.1:8080/?format=json'
A type with json — the structure arrived. Code 403 — the requesting address is not allowed in http-access; a redirect to https — the http-redirect-to-https default is in effect, so repeat over https with the -k option; type text/html — the request went to the human page.
◇

What else to read

3 articles

◇The activation key is a prerequisite for installation, not a step after itWithout an activation key from SparkPost support the engine neither installs nor runs, and the license tier sets the outbound connection ceiling: on Standard everything above 200 is ignored.◇Cloud restrictionsClouds restrict outbound mail on port 25 until you ask them to lift the limit, and mailbox providers treat their address ranges with suspicion.◇How to turn a sending plan into hardwareTwo constants for sizing any node: about 2 KB of memory per queued recipient and spool space proportional to the total size of the messages.

In the Hub
Cost of a mistake
safe: a wrong value breaks nothing
Scenarios
Prepare a node for sending