Demo
Demo

Knowledge base

PMTA knowledge base›Block Global›Directive§ 3.3.1.55.4

domain-macro

Globalset by the Hub

A name for a list of domains, substituted in other lines
in the configuration this is a linedomain-macroinside the block Global
A list of domains named once

The line declares a name and a list of domains bound to it, separated by commas. After that this name with a dollar sign is substituted where a list is needed: in a recipient block <domain $name>, in domain-based acceptance relay-domain, in a signing key declaration domain-key.

The name may contain only letters, digits and underscores — the manual states this directly.

The point is practical: a major receiver serves dozens of domains, and keeping them as a list in every rule is unreadable. One macro — one place to edit.

The main trap is that a macro is edited in one place but acts in many. By adding a domain to the list, you added it to all blocks where the name is substituted — including the one you forgot about. The reverse is the same: by removing a domain, you removed the acceptance rule for it along with the sending policy.

What needs checking is not the macro line but all substitution places.

The other half is minor: the name is checked for letters, digits and underscores. A hyphen in the name — a common habit from domain names — does not work here.

What the Hub does. It writes it — in the recipient policies template, one macro per major mailbox provider: mailru, rambler, ukrnet and so on, fourteen in total.

The layout there is exactly the one macros were made for: the macro line lists the receiver’s domains, followed by a <domain $name> block with its policy — limits, retries, bounce deadline.

Recommended values

What to set. The value is a name and a list; the rules follow from the purpose:

Property Why
name by receiver, not by attribute the list is edited together with the receiver, not with the idea
only letters, digits, underscores an engine requirement
one macro — one receiver otherwise an edit affects other rules

An “all major ones” macro looks convenient and turns out to be dangerous: receivers have different policies, and combining them in a list means losing the ability to tell them apart.

The syntax and the restriction on name characters come from the manual, § 3.3.1.55.4. The “macro plus recipient block” layout comes from the Hub’s policies template. The breakdown of requirements is ours.
Example configuration
# this is how the Hub writes policies: a macro per receiver, then its block
domain-macro mailru mail.ru,bk.ru,inbox.ru,list.ru<domain $mailru>
    max-errors-per-connection 10
    retry-after 30m
</domain>
Editing the list changes the behavior of all blocks where the name is substituted. Check the substitution places, not the macro line itself.
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 ends2 mistakes▶

Editing the list without checking the substitution places

our experience

What it costsAn added domain gets into all blocks where the name is substituted — including acceptance rules and signing key declarations. A removed one disappears from there too.
How to spot itAfter a macro edit, behavior that was not touched has changed.
How to do it rightBefore editing, find all substitutions of the name and decide on each.

Using a hyphen in the macro name

§ 3.3.1.55.4

What it costsOnly letters, digits and underscores are allowed. The engine will not accept a name with a hyphen, and the configuration will not be applied at all.
How to spot itThe configuration check reports an error in the macro line.
How to do it rightWrite an underscore instead of a hyphen.
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
domain-macro MACRO-NAME DOMAIN-LIST
Values
a name of letters, digits and underscores, then a comma-separated list of domains
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
Global
How many times
may be repeated
Everything here comes from the manual, with the section.
Inheritance
The directive is written at the root of the configuration file and applies to the whole node: one macro per instance. It has no inheritance — it is name substitution, not a setting with a value.
⇄

Related directives

2 relations

Works together with

domain-keyGlobalA signing key can be declared for a list of domains at once by substituting the macro name. § 3.3.1.55.1relay-domainGlobalMakes it possible to list several accepted domains in one line by substituting the list name. § 3.3.1.54.2

Referenced from

domain<address-list>Another way to name a group of domains with one word — a macro substituted into recipient rules. § 3.3.5.5

How to check on the node
You need to look at both the declaration and all substitution places:
grep -n '^domain-macro' /etc/pmta/config
grep -n '\$[a-zA-Z_][a-zA-Z0-9_]*' /etc/pmta/config | head -20
The second command shows where the name is substituted. Editing the list affects all these places at once — including those not thought about during the edit.
◇

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
Value
The Hub picks it itself — pace, warm-up stage, metrics
Cost of a mistake
safe: a wrong value breaks nothing
Scenarios
Tune the pace for a provider
Neighboring settings of the block Global:postmasterincludevolume-audit-api-keythread-reusethread-max-priorityAll 108 directives of the block →