Demo
Demo

Knowledge base

PMTA knowledge base›Block <virtual-mta-pool>›Directive§ 3.3.13.4

include-headers-from

<virtual-mta-pool>

A headers file shared by the pool's addresses
in the configuration this is a lineinclude-headers-frominside the block <virtual-mta-pool>
The same name 2:Global<virtual-mta><virtual-mta-pool>— some of them are other settings, some are the same one
One headers file for the whole group of addresses

The line names a headers file for all pool members. There is only one point to writing it here — not to repeat it for each member.

But how it combines with other levels the manual does not say. The adding-up rule is stated only for the node and the sending address: “if the sending address already has its own line, both are applied.” About the pool — silence, and a member overrides the other pool directives in the usual way.

The practical conclusion is not to rely on it. Keep the file on one level and check the result on a delivered message: that is the only way to find out what you got.

The main trap is completing the rule for the manual. Adding up is documented for the “node plus sending address” pair; for a pool the behavior is unknown. A configuration that counts on adding up through a pool may not work that way, and the error will show up as duplicated or missing headers, not as a message at apply time.
What the Hub does. It does not write it: headers are formed by the sending side, and the node only removes the excess. The line is yet another example of a pool as a scope: if a wave of addresses needed an identical headers file, it would be written here once instead of being repeated for each.
Recommended values

The value is a file path, as on the other levels. One thing is decided here — where to keep the file:

Level Who gets it What is known about adding up
node all sending addresses adds up with the address level — documented
pool members not documented
sending address only that address adds up with the node level

Until verified by experience, keep the file on one level.

Inheritance by members comes from the manual (§ 3.3.13). That the adding-up rule for a pool is not described is our observation from comparing the two sections.
Example configuration
# a shared headers file for the whole wave of addresses
<virtual-mta-pool warmup-wave-3>
    include-headers-from /etc/pmta/wave3-headers.txt    virtual-mta mta1
    virtual-mta mta2
</virtual-mta-pool>
Both members will get this file. If mta1 gets its own line, the manual does not describe what will happen: adding up is specified only for the node level.
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▶

Counting on the pool adding up with the sending address

our experience

What it costsThe adding-up rule is documented only for the node. A configuration built on an assumption may produce the wrong set of headers — and without a single error at apply time.
How to spot itSome of the expected headers are missing from the message, or there are extra ones.
How to do it rightKeep the file on one level and check with a message. If adding up through a pool is really needed, test it on a staging setup first.

Adding a member's own file on top of the pool's

§ 3.3.13

What it costsFor other pool directives a member’s own line replaces the pool one entirely. Here the behavior is not described, and the expectation that it “will be added” is not backed by anything.
How to spot itOne member’s set of headers differs from the others unpredictably.
How to do it rightCombine everything needed into one file for this member — then the result is known in advance.
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-headers-from <see-reference>
Values
a path to a file with headers in RFC 2822 format
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<virtual-mta-pool>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The pool is the middle of three levels, and for this directive it is described worse than the others. Only one thing is documented: the node line adds up with the sending address line. What the pool line does — whether it is overridden by a member, like other pool directives, or adds up, like the node line — the manual does not say.
⇄

Related directives

2 relations

Same name in other blocks

include-headers-fromGlobalThe manual gives the definition at the node level; here there is only what writing it at the pool level changes. § 3.3.1.55.3

Applies to

A group of sending addresses with traffic sharesOne of the seven directives a pool hands out to its members. § 3.3.13.4

How to check on the node
Check only on a delivered message. The configuration shows only how many files are involved:
grep -rn include-headers-from /etc/pmta/config
More than one line in the output is a reason to look at the message source: what exactly added up and what was overridden is known only from there.
◇

What else to read

3 articles

◇Headers the sender uses to control deliverySix control headers let the submitting side choose a stream, tag a message with a job, set signing options and the key, the envelope identifier and the schedule; each is allowed separately and per source.◇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.◇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.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Sending address rotation
Neighboring settings of the block <virtual-mta-pool>:virtual-mtadomain-keymax-smtp-msg-ratemax-smtp-outsuppression-listsAll 9 directives of the block →