Demo
Demo

Knowledge base

PMTA knowledge base›API endpoint§ 8.3.3.8

Receiver policy inside an address

VirtualMTA domain operations
The narrowest merge level

Creates, reads, extends and deletes <domain> blocks inside a sending address created through the API.

Paths. GET /config/vmtas/name/domains — the address’s domains; GET, POST, PUT, PATCH and DELETE on /config/vmtas/name/domains/domain — read, create, replace, extend and delete a block; DELETE …/domains/domain/key/directive — remove all lines of a directive.

A domain name may contain macros — they are not expanded but carried into the generated file as is. A star works too: …/domains/*.

The block applies only to messages sent through this address, and for them it overrides what is set for the same domain in the pool the address belongs to.

First enable http-enable-api-config; a change requires the key from http-api-key.

The main trap is expecting the API to expand a macro. A name like yahoo.$tld is stored and returned literally, and the engine expands it when reading the generated file — according to the domain-macro declaration. The GET …/domains list shows one line with the macro, not the domains it will cover.
What the Hub does. It does not use it: the Hub writes receiver blocks into configuration files, and http-enable-api-config is not enabled on the nodes.
Recommended values

What each method does:

Method Path Action
GET /config/vmtas/name/domains the address’s domains
GET …/domains/domain the block’s lines
POST …/domains/domain create; an error if the block exists
PUT …/domains/domain replace the lines entirely
PATCH …/domains/domain append lines
DELETE …/domains/domain delete the block
DELETE …/domains/domain/key/directive remove all lines of a directive
The paths, methods and macro handling come from the manual (§ 8.3.3.8–8.3.3.14); the block applying only to its own address and overriding the pool are § 3.3.12–3.3.13. The trap analysis is ours.
Example configuration
# disable signing for one receiver inside a sending address
curl -s -X PATCH 'http://127.0.0.1:8080/config/vmtas/vmta1/domains/example.com' -H 'X-API-Key: KEY' -H 'Content-Type: application/json' -d '{"directives":["dkim-sign no"]}'
PATCH appends lines to an existing block; if the block does not exist yet, it is created with POST.
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

1 relation

Applies to

How the policy for a receiver is assembledThe mechanism that is visible here. inference

Referenced from

Sending addresses through the configuration APIA neighboring catalog entry. § 8.3.3.8

How to check on the node
See the receiver blocks of an address:
curl -s 'http://127.0.0.1:8080/config/vmtas/vmta1/domains'
curl -s 'http://127.0.0.1:8080/config/vmtas/vmta1/domains/example.com'
A “no such address” error for an address that works on the node means it is defined in the file: the API sees only its own addresses and will not nest a block into someone else’s.
◇

What else to read

3 articles

◇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.◇How the policy for a receiver is assembledSettings are assembled from the most general pattern to the most precise; the order of blocks in the file means nothing.◇Backoff mode — the queue's second personalityA queue that a receiver has started refusing switches to a parallel set of limits, retries and routes — ten directives that act only in this mode.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Tune the pace for a provider