Knowledge base

PMTA knowledge base›Block Global›Directive§ 3.3.1.58.25

http-enable-api-config

Globalrestart required

Whether to enable configuration editing over HTTP

in the configuration this is a linehttp-enable-api-config falseinside the block Global

A second configuration that is not in the file

The interface appeared in PowerMTA 5.5 and allows reading and changing individual parts of the configuration over HTTP. Currently these are two kinds of entries: address lists (including suppression lists) and sending addresses with their receiver tags. It is off by default.

🔴 What is created through this interface can be changed only through it. The manual says it directly: “Any configuration created via this API can only be modified via the API.” These entries are not in the configuration file — they live in separate files, /var/lib/pmta/config-api on Linux, and are loaded on every reload.

So the node gets two sources of truth. Whoever reads the configuration file does not see the whole configuration. For a fleet that assembles the file as a whole and distributes it to nodes, this is a direct problem: our file does not describe the node.

Disabling does not delete. The entries become invisible and will come back if the interface is enabled again. A forgotten edit can resurface a year later.

Every edit triggers a reload. If it fails, the edit is rejected, and the error text is returned in the response — sometimes a confusing one: an attempt to delete a list in use gives “no such list,” because the deletion was rolled back.

The main trap is enabling it “to have a look” and creating one entry. From then on the configuration file stops being a description of the node, and the difference is discovered not right away but at the first mismatch between behavior and expectations. Disabling the interface does not remove the difference, it hides it.

What the Hub does. It does not write it — the interface stays off, and that is deliberate. The Hub assembles the node’s configuration as a whole and puts it in place as a file; a second configuration living outside the file would break that rule.

🔴 If a node arrives with someone else’s configuration, this is worth checking first. An http-enable-api-config yes line means some of the node’s settings are not in the file, and a migration will not capture them: the /var/lib/pmta/config-api directory has to be moved separately.

Recommended values

For a fleet there is one answer, and it is the default:

Value	When
no (default)	the configuration is assembled and distributed by the Hub
yes	the node is configured by someone else’s program over HTTP

The two methods cannot be combined: entries created by the interface can be edited only by it.

The false default, both kinds of entries, the rule “what is created via the API is edited only via the API,” the storage directory and the automatic reload come from the manual (§ 3.3.1.58.25, § 8.3). The conclusion about two sources of truth for a fleet is ours.

Example configuration

# enable it only where the node is configured by someone else's program
http-mgmt-port 1000
http-api-key abcd_0123_abcd_0123_abcd_0123_ab
http-enable-api-config yes

The key next to it is mandatory: reading may pass by access level, while editing passes only with the key.

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▶

Moving a node while taking only the configuration file

§ 8.3

What it costsAddress lists and sending addresses created through the interface are not in the file. They will not be on the new node, and the difference will show up in behavior, not as an error.

How to spot itAfter the move, suppression does not fire or a sending address is not found.

How to do it rightMove the /var/lib/pmta/config-api directory together with the file.

Disabling the interface to “remove” what was created through it

§ 8.3

What it costsThe entries are not deleted but hidden. Enabling it again will bring them back — sometimes months later, when the reason is no longer remembered.

How to spot itAfter the interface is enabled, unfamiliar lists and sending addresses appear.

How to do it rightDelete entries through the interface itself, and only then disable it.

Taking an edit error message at face value

§ 8.3

What it costsEvery edit triggers a reload, and on failure it is rolled back entirely. A “no such list” response to a deletion means the deletion was rejected, while the list is in place and in use.

How to spot itThe error describes something other than what you were doing.

How to do it rightRead the response as the result of a reload: first find out who uses the entry, and only then delete it.

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.

Reference data

Syntax: http-enable-api-config <boolean>
Values: yes | no | true | false
Default: false § 3.3.1.58.25
Applying: a service restart is required
Queue: will not touch what is already queued
Where to write it: Global
How many times: once in the block

Everything here comes from the manual, with the section.

Inheritance

There is no inheritance: the line is written at the root of the file, in the Global section. The interface is either enabled for the whole node or not; it cannot be enabled selectively by entry type or by address.

⇄

Related directives

4 relations

Does not work without

http-api-keyGlobalReading may pass by access level, but editing always requires a key. § 8.3 Sending addresses through the configuration APIOne of the two kinds of entries this interface allows creating. § 3.3.1.58.25

Depends on

http-accessGlobalWhat was created can be read by access level, but changed only with a key. inference

Applies to

http-mgmt-portGlobalThe interface answers on the same port as the monitor itself. § 8.3

How to check on the node

We check whether part of the configuration has been created outside the file:

ls -la /var/lib/pmta/config-api/ 2>/dev/null

A non-empty directory means entries were created through the interface — even if the line itself is off now. When moving a node, this directory has to be taken along with the configuration file.

◇

What else to read

3 articles

◇Accept, route, deliverA message’s path inside the node: accept, decide where, deliver — and all the settings live between these three steps.◇Four value types the whole config is written inBoolean, domain pattern, regular expression and time interval — defined once in § 3.2 and then used by all directives.◇Reloading settings versus restarting the serviceThe configuration is read at startup, and after that edits are picked up by the reload command — except for the directives the manual marks as requiring a restart.

In the Hub

Cost of a mistake: reversible: harms only while it is set
Scenarios: Configuration lifecycle

Neighboring settings of the block Global:smtp-source-host domain-key smtp-proxy-source-host host-name postmaster All 108 directives of the block →