Demo
Demo

Knowledge base

PMTA knowledge base›Block Global›Directive§ 3.3.1.55.3

include-headers-from

Global

A file of headers inserted into every message
in the configuration this is a lineinclude-headers-frominside the block Global
The same name 2:Global<virtual-mta><virtual-mta-pool>— some of them are other settings, some are the same one
Identical headers in all messages — as a file

The line names a file; its contents — headers in the usual mail format — are inserted into every message that goes out through a sending address. The insertion place is specified: right after the Received the node itself adds.

Inheritance here is not like that of other directives. The manual says directly: a line set at the node level goes to all sending addresses, and if a sending address already has its own, both are applied. This is the only directive of the block where values add up rather than override each other.

Headers are not the place for internal information. Everything written here will be seen by the recipient: node names, internal identifiers, system names.

The main trap is adding up mistaken for overriding. Having written a file at the node level and “its own” for a sending address, you will get both sets of headers in the message, not the second instead of the first. Duplicates of headers that must appear only once are already a deliverability issue.
What the Hub does. It does not write it: message headers are formed by the sending side, while the node, on the contrary, removes the excess — remove-header cleans out the platform’s service headers, and add-received-header is turned off. A headers file would come in handy for something that must be in every message regardless of the sender — for example, a link to a policy; we have no such requirements yet.
Recommended values

The value is a file path. What to consider when filling it:

What goes in Worth it Why
List-Unsubscribe no, better set by the sender the unsubscribe address depends on the recipient, while the file is one for all
a link to a policy or a contact yes it is the same for all messages
internal identifiers no the recipient will see them
something the platform already sets no you will get duplicates: values add up

Checking for duplicates is mandatory: additive inheritance is the main source of repeated headers.

The insertion place and the adding-up rule come from the manual (§ 3.3.1.55.3). What to put into the file is ours.
Example configuration
# a headers file shared by the node
include-headers-from /etc/pmta/common-headers.txt
# this sending address has its own — BOTH files will apply
<virtual-mta shop-example-com>
    include-headers-from /etc/pmta/shop-headers.txt
</virtual-mta>
That is exactly what the manual says: both lines take effect. A message through shop-example-com will get headers from both files, and if they contain identical names, those will appear in the message twice.
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▶

Expecting the sending address file to replace the shared one

§ 3.3.1.55.3

What it costsBoth apply. The message gets headers from two files, and same-named ones twice. Some receivers treat duplicates of mandatory headers more strictly than their absence.
How to spot itIn the source of a delivered message, identical headers appear twice.
How to do it rightKeep the file in one place: either shared on the node or its own for each sending address — but not both at once.

Putting an unsubscribe address into the file

our experience

What it costsThe file is one for all messages, while an unsubscribe link must be personal. A shared List-Unsubscribe either does not work or unsubscribes the wrong person.
How to spot itUnsubscribes do not reach the sender or arrive without indicating who unsubscribed.
How to do it rightSet such headers on the sender’s side, where the recipient is known. The file is for what is truly the same for everyone.
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 FILENAME
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
Global, <virtual-mta>, <virtual-mta-pool>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
🔴 An exception to the general rule. For other directives a value from a more specific block overrides the general one; here they add up: the manual states directly that when a sending address has the line set, both apply. The manual says nothing about the <virtual-mta-pool> level — the adding-up rule is stated only for the node and the sending address.
⇄

Related directives

1 relation

Applies to

Sending addressThe headers are inserted into all messages of a sending address; a line written at the node level goes to each of them. § 3.3.1.55.3

Referenced from

include-headers-from<virtual-mta>The manual gives the definition at the node level; here is only what writing it inside a sending address changes. § 3.3.1.55.3include-headers-from<virtual-mta-pool>The 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

How to check on the node
Check on a delivered message: send one to your own mailbox and look at the source. Where the line is set:
grep -rn 'include-headers-from' /etc/pmta/
In the message the headers should be right after Received. If each appears twice, adding up has taken place: the file is set both on the node and for the sending address.
◇

What else to read

3 articles

◇A license for a fleet, not for a serverThe license is not bound to a server: it is installed on as many machines as the instance limit allows, and the nodes send volume statistics to the vendor every hour.◇How the node selects a source and combines its settingsA connection falls under all source blocks whose addresses cover it, and they act merged — the narrow one overrides the wide one; named blocks are attached only by direct reference.◇Address lists — named and unnamedA list of addresses, domains, patterns or hashes; a named one is attached by directives such as suppression, an unnamed one lives inside an inbound mail processor.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Sender isolation
Neighboring settings of the block Global:host-idmailmerge-expands-undefined-variablespickup-remove-dothost-namepostmasterAll 108 directives of the block →