Demo
Demo

Knowledge base

PMTA knowledge base›API endpoint§ 8.4

Run a command over the network

critical

/command
🔴 The node’s console, reachable by a request

Runs a node console command passed in the request — almost any that pmta understands.

The call is POST /command with the form fields command — the command text without the word pmta — and format. The response format is json or xml with a structure, or json-text and xml-text: console text wrapped in a document.

The exceptions are named in the manual: register, deregister and interactive commands such as resolve –interactive cannot be run this way.

🔴 This is a full console over the network: message deletion, queue mode changes and configuration reloads all go through here. The manual authorizes the request with the key from http-api-key in the X-API-Key header, and the key grants full access from any address — keep it like an administrator password.

The main trap is judging success by the response code. A command refusal arrives with code 200: the outcome is in the status field and the reason in message. Parsing that looks only at the code takes a refusal for an executed command.

And a second one, noticed by the Hub on a live engine: json-text returns an empty string for some commands where json returns a structure.

What the Hub does. It uses it constantly — this is its node control channel. Cabinet operations — pausing and resuming a queue, backoff and normal mode, retry, withdrawing and restoring an address, deleting a queue, reloading the configuration, flushing the DNS cache, rotating logs — go here with the node key and the json format. Reading commands come from here too: state, paused queues and queues in backoff mode, withdrawn addresses.

Over SSH only stopping, starting and restarting the service go; applying the configuration — writing files, checking and reloading — also goes over SSH.

Recommended values

Which format to take:

format What arrives When
json a structure in data for a program — this is how the Hub reads it
xml a structure in XML for a program that prefers XML
json-text console text as a string in data to show a person as is
xml-text console text in XML the same for XML
The command and format fields, the four formats, the exceptions and key authorization come from the manual (§ 8.4, § 3.3.1.58.5). The outcome in the status field with code 200 and the empty json-text for some commands are the Hub’s observations.
Example configuration
# a console command over the network: the key from http-api-key
curl -s -H 'X-API-Key: KEY' 'http://127.0.0.1:8080/command' -F command='show version' -F format=json
The manual authorizes commands with the key; a request without the key would also run into the http-csrf-protection protection, which is on 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

4 relations

Does not work without

How the node decides whether to let an HTTP request inThe mechanism that is visible here. § 8.4

Depends on

Command output formatsThe mechanism that is visible here. § 8.4

Conflicts with

Connect the node to the vendor's consoleThe same output from the command line. § 8.4Resolve a name and connectThe same output from the command line. § 8.4

How to check on the node
Check that the command goes through and the outcome is read from the body:
curl -s -H 'X-API-Key: KEY' 'http://127.0.0.1:8080/command' -F command='show version' -F format=json
grep -n 'http-api-key' /etc/pmta/config
In the response look at the status field: success means the command was executed. Code 403 means the key matched no http-api-key line.
◇

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
dangerous: effects outlast a rollback
Scenarios
Emergency stop · Collect telemetry
Priority
critical