Demo
Demo

Knowledge base

PMTA knowledge base›API endpoint§ 8.3.3

Sending addresses through the configuration API

VirtualMTA operations
The same construct, managed over HTTP

Creates, reads, extends and deletes sending addresses with requests: an address is described by a set of directive lines in JSON.

Paths. GET /config/vmtas — the names of addresses created through the API; GET, POST, PUT, PATCH and DELETE on /config/vmtas/name — read, create, replace, extend and delete an address together with nested domains; DELETE /config/vmtas/name/key/directive — remove all lines of one directive.

Lines are placed in the order they were added, and one directive can repeat.

Enable it first: http-enable-api-config yes, off by default. The engine checks every change with a reload and rejects the change if the reload fails.

The same <virtual-mta> as in the file, only created by a request — and it can only be edited further by requests.

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

The main trap is a name already taken in the file. The GET /config/vmtas list shows only addresses created through the API: it cannot tell whether a name is free — only the whole configuration can.
What the Hub does. It does not use it: the Hub writes sending addresses into the /etc/pmta/virtualhost.txt file and reloads the configuration, and http-enable-api-config is not enabled on the nodes.
Recommended values

What each method does:

Method Path Action
GET /config/vmtas the names of addresses created through the API
GET …/name the address’s directive lines
POST …/name create; an error if the address exists
PUT …/name replace the lines entirely
PATCH …/name append lines
DELETE …/name delete together with nested domains
DELETE …/name/key/directive remove all lines of a directive
The paths, methods, line order and checking by reload come from the manual (§ 8.3, § 8.3.3). The analysis of names from the file is ours.
Example configuration
# create a sending address with a request
curl -s -X POST 'http://127.0.0.1:8080/config/vmtas/vmta1' -H 'X-API-Key: KEY' -H 'Content-Type: application/json' -d '{"directives":["smtp-source-host 192.0.2.10 mta1.example.com"]}'
Each array element is a directive line, as in the file. The engine reloads the configuration itself and rejects the change on error.
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

Works together with

Receiver policy inside an addressA neighboring catalog entry. § 8.3.3.8

Can be replaced by

Effective settings of a sending addressThe same output from the command line. inference

Where you can see it

The sending address — what it is made ofThe mechanism that is visible here. § 8.3.3

Referenced from

http-enable-api-configGlobalOne of the two kinds of entries this interface allows creating. § 3.3.1.58.25Configuration through the API and the file do not reconcileA request that returns the same thing. § 8.3.3

How to check on the node
See what was created through the API:
curl -s 'http://127.0.0.1:8080/config/vmtas'
curl -s 'http://127.0.0.1:8080/config/vmtas/vmta1'
The first response gives the names of addresses from the API, the second their lines. Addresses from the configuration file are not here.
◇

What else to read

3 articles

◇Warm-up built into the engineA warmed-up address hands the first N messages of the day for each receiver to its cold partner; the partner sends them itself and builds history.◇The sending address — what it is made ofA named set of everything that is a property of the address: which IP the message leaves from, how the node introduces itself, what it signs with and how fast it sends.◇A group of sending addresses with traffic sharesA named group of sending addresses; without shares messages are distributed in rotation, with shares in the given proportion, in steps of a tenth of a percent.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Sending address rotation · Address warm-up