Demo
Demo

Knowledge base

PMTA knowledge base›API endpoint§ 5.3

The whole node state in one document

critical

/status
The only endpoint the manual describes in full

The request returns the node’s entire state at once, as a structure. The format is your choice — XML or JSON, and the structures match field for field, so the reading side can take either.

This is the only endpoint for which the manual gives the full output — and in both formats. For the others the documentation is sparser.

Its coverage is wider than that of the page it mirrors. Besides traffic and queues, the response carries the product name, version, build date and revision; the license serial number; information about the machine; the state of the resolver and the spool; a flag for whether the node is running.

Hence its role: one request gets a snapshot that is enough both for monitoring and for identifying the node — what version, what license, how much is in use.

The main trap is taking a snapshot for a history. The response describes a moment: how many connections are open now, how many recipients are in the queue now. Two consecutive requests give two points, not the interval between them: everything that happened between the measurements and managed to end will not get into either. For events there is accounting, for state this request, and one cannot be substituted for the other.
What the Hub does. This is the main source of its telemetry. The node poll takes five endpoints at once, and this is the first: traffic, the queue, connections, the spool and machine information come from it.

⚠️ What is not in the response, we do not have either. The license level comes as a serial number, not a tier, so the connection ceiling is unknown to the Hub (licensing). Events between measurements are lost: the poll will miss a queue’s short spell in backoff mode (backoff-mode).

The Hub gets accounting separately — as a stream through a webhook, not with this request. The separation is right: state is queried, events are received.

Recommended values

What to ask with this request and what not:

Question Does it answer
what is going on with the node now yes — that is its purpose
which version and license yes, including the serial number
how many messages went out in the last hour no — that is accounting
when the queue was in backoff mode no — that is the queue history

The format is chosen by the reading side. The structures match, so there is no difference beyond parsing convenience.

The polling frequency is a compromise. More often means fewer missed events and more load; less often, the opposite. Events that must not be missed are more reliably taken from accounting than by polling more often.

The “state versus events” separation is ours. From the manual here are the composition of the response, the two formats with matching structures and the fact that the coverage is wider than the status page.
Example configuration
# a node snapshot in one request
curl -s 'http://127.0.0.1:8080/status?format=json'curl -s 'http://127.0.0.1:8080/status?format=xml'
The highlighted line returns the same as the second one — the structures match field for field. The choice of format affects nothing except the convenience of parsing.
yellow — — directive names, blue — blocks. They are highlighted the same way in the text of the card.
▲

Common mistakes and problems

what people get wrong and how it ends3 mistakes▶

Building a history from consecutive snapshots

§ 5.3

What it costsThe response describes a moment. Everything that happened between two measurements and managed to end will not get into either of them — and the reconstructed history will be the poorer the less often the poll runs.
How to spot itThe constructed history has fewer events than there actually were, and the boundaries are multiples of the polling period.
How to do it rightTake events from accounting, and use this request for state. Polling more often does not solve the problem, only softens it.

Expecting the serial number to reveal the license level

§ 5.3

What it costsThe response has a serial number, not a tier. The connection ceiling the license silently imposes cannot be derived from this response — and a system that calculates limits will not learn about it.
How to spot itThe calculated rate is not reached, while everything in telemetry is normal.
How to do it rightAsk for the license level with a command on the node. It is not in the request’s response.

Exposing the endpoint to the outside for convenience

§ 5.3

What it costsThe response carries the version, the license, machine information and queue state — an almost complete description of the node. Reachable from the internet, it saves an outsider the reconnaissance.
How to spot itThe web monitor port responds not only from the machine itself.
How to do it rightKeep access by rights and from restricted addresses. Expose only what is really needed outside.
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.
Inheritance
An API endpoint has no inheritance: it is a request address. The web monitor access settings are inherited — the port and rights — and they are set at the node level with the http-mgmt-port and http-access directives.
⇄

Related entries

4 relations

Depends on

Monitor response formatsTwo response formats with matching structures — the choice is up to the reading side. § 5.1

Can be replaced by

Node statusThe same status page, only for a human. § 5.3Node status in the consoleThe same state from the command line. inference

Where you can see it

ConnectionsOne of the numbers in the response: how many connections are open at this moment. § 5.3

Referenced from

Traffic countersThe metric comes in the status snapshot — with the same request as all the others. § 5.3Web monitor rootA neighboring catalog entry. § 5.3Node metrics in a standard formatThe same snapshot of the current state, only in its own format and without our key. § 11.22

How to check on the node
Check that the endpoint is available and that the response contains what is expected:
curl -s 'http://127.0.0.1:8080/status?format=json' | head -40
pmta show status
The second command prints the same in the console — it is a convenient way to check that the request returns the full picture rather than one truncated by access rights.
◇

What else to read

3 articles

◇Exposing metrics to a collectorExposing the node’s metrics to an external collector in its format.◇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.◇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.

In the Hub
Cost of a mistake
safe: a wrong value breaks nothing
Scenarios
Capacity planning · Collect telemetry
Priority
critical