Demo
Demo

Knowledge base

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

include-headers-from

<virtual-mta>

A headers file for messages from this sending address
in the configuration this is a lineinclude-headers-frominside the block <virtual-mta>
The same name 2:Global<virtual-mta><virtual-mta-pool>— some of them are other settings, some are the same one
Its own headers file — in addition to the common one

The syntax is the same. The scope changes — and, unlike the block’s other directives, the way of inheritance does not change.

The values add up. The manual says so directly: if the line is set at the node level and here, both apply. This is the only <virtual-mta> directive that behaves this way; for its neighbors in the block, their own value overrides the common one.

Hence its use: here goes what belongs specifically to this sending address and should be added to the common set rather than displace it.

The main trap. The habit of “your own overrides the common” is wrong here. A file written here “instead of” the common one cancels nothing — the message will get both sets of headers, and same-named ones will appear in it twice.
What the Hub does. It writes it neither here nor at the node level. Headers are formed by the sending side; the node, on the contrary, strips the excess — remove-header cleans out the platform’s service headers, and add-received-header is off.
Recommended values

The value is a file path, as at the node level. The difference is what should go here:

Level What goes there Keeping the addition in mind
node what is the same for all messages goes to all sending addresses
here what belongs to this address is added to the common set, does not replace it
<virtual-mta-pool> what is common to a group the manual says nothing about addition at this level

Check the message for duplicates after any edit: it is the only reliable way to see the result of the addition.

The addition rule comes from the manual (§ 3.3.1.55.3), in direct wording. The “what goes to which level” breakdown is ours.
Example configuration
# the sending address has its own file — it WILL BE ADDED to the common one, not replace it
<virtual-mta shop-example-com>
    smtp-source-host 203.0.113.10 shop.example.com
    include-headers-from /etc/pmta/shop-headers.txt</virtual-mta>
If a file is also set at the node level, the message will get headers from both. For only this one to apply, the common line has to be removed — otherwise no override will happen.
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▶

Writing a file here to cancel the common one

§ 3.3.1.55.3

What it costsNo cancellation happens: both files apply. The intent “a set of headers of its own here” turns into “the common set plus its own,” and some headers get duplicated.
How to spot itThe message has headers from a file that was not assigned to this address.
How to do it rightRemove the common line at the node level or merge both files into one. This directive cannot be overridden.

Carrying the addition rule over to a pool

our experience

What it costsThe manual states the addition only for the node and the sending address. What happens to the pool value is not described, while a member overrides the other pool directives.
How to spot itThe behavior diverges from expectations, and it can be checked only by experiment.
How to do it rightDo not count on addition through a pool. Keep the file at one level and check the result on a message.
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-global>
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>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
🔴 An exception to the block’s general rule. A value of its own here does not override the common one but adds up with it — so says the manual. It says nothing about the <virtual-mta-pool> level, and the addition rule must not be carried over to it without checking: the other pool directives are overridden by a member in the usual way.
⇄

Related directives

2 relations

Same name in other blocks

include-headers-fromGlobalThe manual gives the definition at the node level; here is only what writing it inside a sending address changes. § 3.3.1.55.3

Applies to

The sending address — what it is made ofOne of the sending address settings: which headers are added to its messages. § 3.3.12.11

How to check on the node
The only reliable check is on a delivered message. From the configuration you can only see that there are two files:
grep -rn include-headers-from /etc/pmta/config
Two lines in the output mean the headers will add up. Next, look at the message source: identical header names in the two files will produce duplicates.
◇

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>:host-namedomain-keysmtp-source-hostproxy-protocolproxy-include-tlvAll 15 directives of the block →