Demo
Demo

Knowledge base

PMTA knowledge base›API endpoint§ 8.3.2

Address lists through the configuration API

critical

address list operations
Editing the configuration with a request

Creates, reads, extends and deletes address and domain lists — suppression lists, for example — with requests, without editing files.

Paths. GET /config/address-lists — the names of all lists; GET, POST, PUT, PATCH and DELETE on /config/address-lists/name — read, create, replace, extend and delete a list; DELETE on …/addresses/address, …/hashed-addresses/address and …/domains/domain — remove one entry. Request bodies and responses are JSON.

Enable it first: the endpoint works only with http-enable-api-config yes, which is off by default.

Objects created this way can only be edited through the API: they are not in the configuration file, and the two ways of describing the same thing do not reconcile. The engine stores them in /var/lib/pmta/config-api.

Reading goes through without a key from an address with the operator level or higher in http-access; any change requires the key from http-api-key in the X-API-Key header.

The main trap is code 200 on an error. A refusal arrives with code 200, and the outcome is in the status field (fail) and the message text. The text can mislead too: deleting a list that is used somewhere makes the reload refuse, and the response says “no such address list” while the list is still there.
What the Hub does. It does not use it: http-enable-api-config is not enabled on the nodes, and the Hub writes its own address lists — for receiving complaints and bounces — straight into the configuration file.
Recommended values

What each method does:

Method Path Action
GET /config/address-lists the names of all lists
GET …/name the list contents
POST …/name create; an error if the list exists
PUT …/name replace entirely; an error if the list does not exist
PATCH …/name extend; duplicates are silently skipped
DELETE …/name or …/name/addresses/address delete a list or one entry
The paths, methods, enabling with a directive, storage in /var/lib/pmta/config-api and errors with code 200 come from the manual (§ 8.3, § 8.3.2, § 8.3.4). The trap analysis is ours.
Example configuration
# add two addresses to a suppression list
curl -s -X PATCH 'http://127.0.0.1:8080/config/address-lists/suppress' -H 'X-API-Key: KEY' -H 'Content-Type: application/json' -d '{"addresses":["a@example.com","b@example.com"]}'
PATCH extends the list, PUT would replace it entirely. After every change the engine reloads the configuration itself.
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

3 relations

Depends on

Configuration through the API and the file do not reconcileThe mechanism that is visible here. § 8.3

Works together with

Compute a hashThe same output from the command line. inference

Where you can see it

Address lists — named and unnamedThe mechanism that is visible here. § 8.3.2

Referenced from

Two attachment points — and two different behaviorsLists are edited over HTTP, without editing the configuration and without a reload — that is what makes the mechanism interesting. § 11.15

How to check on the node
Check whether the API is enabled and what was created in it:
grep -n 'http-enable-api-config' /etc/pmta/config
curl -s 'http://127.0.0.1:8080/config/address-lists'
ls /var/lib/pmta/config-api/
A response with status fail — look at message: the reason the reload was refused is there. An empty list with the directive on means no lists were created through the API.
◇

What else to read

3 articles

◇Address lists — named and unnamedA list of addresses, domains, patterns or hashes; a named one is attached by directives such as suppression, an unnamed one lives inside an inbound mail processor.◇Configuration through the API and the file do not reconcileObjects created through the configuration interface cannot be edited in the file: two sources of truth about the configuration do not reconcile.◇Two attachment points — and two different behaviorsA list attached to a source rejects the recipient at submission or bounces the message later; attached to a sending address or pool, it always accepts and then bounces.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Address suppression · Sender isolation
Priority
critical