Demo
Demo

Knowledge base

PMTA knowledge base›Block <domain>›Directive§ 3.3.10.104

include

<domain>

Include a settings file inside a recipient block
in the configuration this is a lineincludeinside the block <domain>
The same name 4:<domain>Global<smtp-pattern-list><source><virtual-mta>— some of them are other settings, some are the same one
Receiver rules — as a separate file

The form and the rules are the same: a path, a mask or an HTTP address. The lines are read as rules of this recipient.

This is where the mechanism has its clearest use. Rules for major receivers — limits, retries, TLS — change from node to node and over time; moving them into a file and distributing it centrally is simpler than editing every configuration.

It can be repeated — the manual shows a file and an address in a row.

The main trap is that included rules are not visible in the file. Reading the configuration, you see the include line, not what it brought in. Investigating “why this receiver has such a rate” becomes one step longer — and that is exactly the question asked most often.
What the Hub does. It does not write it: it assembles receiver rules itself from the policies template and rewrites them in full. Centralized rule distribution is exactly what the Hub does, only in its own way: the configuration arrives at the node already assembled rather than being pulled by it.
Recommended values

Three forms of the value, as at the node level:

Value When
a file path receiver rules are moved out of the main file
a mask a file per receiver, in one line
an HTTP address rules are distributed centrally

One thing is worth weighing: the convenience of distribution against the rules no longer being readable from the configuration by eye.

The value forms and the address requirements come from the manual (§ 3.3.10.104). The note about readability is ours.
Example configuration
# receiver rules are moved out and distributed centrally
<domain yahoo.com>
    include /etc/pmta/yahoo-limits.txt    include https://mylocalhost.com:4000/domain/yahoo-limits.txt
</domain>
The manual’s example. Both lines take effect; the resulting value is assembled by the usual merge rules of recipient blocks, and it can be seen only on the node 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▶

Looking for a value in the configuration while it is in an included file

our experience

What it costsThe include line does not show what it brought in. The investigation goes through the main file and finds nothing, although the rule is in effect.
How to spot it“There is nothing like that in the configuration,” yet the node behaves as if there were.
How to do it rightLook at the node — pmta show queues shows the result of merging, not the sources.

Putting non-recipient-level directives into the file

§ 3.3.10.104

What it costsThe substitution is positional: the lines are read as contents of the <domain> block. A directive from another context will be a parse error.
How to spot itThe configuration does not apply, and the error points inside the included file.
How to do it rightKeep only receiver rules in such files.
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
include <path-or-url>
Values
a file path, a mask or an absolute http/https address without userinfo, a query string or a fragment
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<domain>
How many times
may be repeated
Everything here comes from the manual, with the section.
Inheritance
The line itself has no inheritance: it is a substitution. The included rules are then inherited as regular <domain> directives — they merge from general to specific, and the most precise match by recipient name wins.
⇄

Related directives

1 relation

Same name in other blocks

includeGlobalThe same directive at the root of the file; there it adds node-level lines. § 3.3.10.104

How to check on the node
The resulting queue rules are visible only on the node, and it is those that need to be looked at, not the file:
pmta show queues yahoo.com/mta1
The queue uses merged rules: the included ones together with those written in place. If the expected value is missing, look for a more precise match by recipient name — it overrides.
◇

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 <domain>:disable-acct-recordsbounce-afterretry-afterdkim-signenable-source-ip-limits-on-sending-ipAll 135 directives of the block →