Demo
Demo

Knowledge base

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

proxy-include-tlv

<virtual-mta>set by the Hub

Whether to pass the queue domain to the proxy — for one sending address
in the configuration this is a lineproxy-include-tlvinside the block <virtual-mta>
The same name 1:Global<virtual-mta>— some of them are other settings, some are the same one
The middle level: what the proxy learns about the message

The line adds a field with the queue domain to the protocol header. There is only one type so far — domain, and the engine fills in the value itself.

It requires the second protocol version — the first has no additional fields.

There are three levels, and this is the middle one: the most specific is include-tlv in the proxy block itself, then this line, then the same line at the node level.

The queue domain is not always the recipient domain. It is the queue name: with MX rollup or queue renaming it is different.

The main trap is forgetting about the third level. A line in the <proxy> block is stronger than this one, and the sending address setting does not affect it.
What the Hub does. It writes domain in every sending address that goes through a proxy — in the proxy-<tag> blocks of /etc/pmta/proxy.txt, next to proxy-protocol 2.

🔎 The queue domain travels to the gate in the PROXY header, and the gate learns the receiver without looking into the SMTP conversation. It picks the proxy to go out through not by the domain but by the tag from the smtp-proxy-source-host line.

Recommended values

The value is chosen by what the proxy can do:

Value When
do not set it the proxy decides by the pair of addresses
domain the proxy spreads traffic by direction
The only field type, its code, the automatic substitution of the queue domain and the second-version requirement come from the manual (§ 3.3.1.49).
Example configuration
# without the second version the line adds nothing
proxy-protocol 2
proxy-include-tlv domain
The field will carry the queue name, and with MX rollup that is the group’s common name.
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 ends1 mistake▶

Enabling the field with the first protocol version

our experience

What it costsThe first version has no additional fields: the line will silently add nothing.
How to spot itThe line is set, but the proxy does not receive the domain.
How to do it rightSet the second version — in the proxy block or with the proxy-protocol line.
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
proxy-include-tlv <see-global>
Values
domain
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
The line lives in <virtual-mta> and overrides the same node-level line for this sending address. It is itself overridden by the line of the same name in the <proxy> block.
⇄

Related directives

2 relations

Same name in other blocks

proxy-include-tlvGlobalThe level above: if not set here, the setting is taken from there. § 3.3.1.49

Applies to

The sending address — what it is made ofA setting of one sending address: a neighboring one may have a different value. § 3.3.12.9

How to check on the node
Check it on the proxy — in the connection header:
tcpdump -A -i any -c 20 'port 5000'
The field comes as a binary block with code 0xE0 and the domain string in UTF-8.
◇

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
Value
The Hub picks it itself — pace, warm-up stage, metrics
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-protocolinclude-headers-fromAll 15 directives of the block →