Demo
Demo

Knowledge base

PMTA knowledge base›Block <source>›Directive§ 3.3.7.53

retain-x-virtual-mta

<source>

Whether to keep the processed X-Virtual-MTA header in the message
in the configuration this is a lineretain-x-virtual-mta falseinside the block <source>
Remove the header or leave it to the recipient

The default is false, that is, remove. The header has done its job — chosen the stream — and the recipient does not need it after that.

The line acts only as part of a pair. It makes sense only where process-x-virtual-mta is yes and the header is present in the message. Without processing the header stays in the message anyway, but for a different reason — it simply was not read.

Why keep it at all. The only practical reason is an investigation using a copy of the message taken somewhere further along the path: the stream name is visible right in the source. The price is that the recipient sees it too.

The main trap. Stream names in a fleet are telling — domain, role, address number. A header left in place shows the recipient the structure of the infrastructure, giving nothing in return: for investigations the same name is already in accounting, in the vmta field.
What the Hub does. It does not write it — it keeps the vendor default, that is, removes it. The Hub already gets the stream name for every message from accounting, and there is no reason to show it to the recipient. This is also consistent with the general approach of the working configuration: the platform’s service headers are removed, add-received-header is off.
Recommended values

What to set. Practically always the default:

Value When
no (default) always, unless there is a reason otherwise
yes temporarily, during an investigation, when a copy of the message with the stream name is needed

There is no point keeping yes permanently: the same name is in accounting, and it is easier to search there.

The false default and the condition “only with processing enabled” come from the manual. The advice to keep it off is ours.
Example configuration
# for the duration of an investigation: the message will arrive with the stream name in the header
<source 10.0.0.0/24>
    process-x-virtual-mta yes
    retain-x-virtual-mta yes</source>
Without the process-x-virtual-mta line this one means nothing. And it is a temporary setting: after the investigation it is returned to the default, otherwise stream names go to every recipient.
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▶

Leaving it on after the investigation

§ 3.3.7.53

What it costsEvery message carries to the recipient the name of the stream it went out through. For a fleet with telling names, that is a description of the internal structure handed out for free.
How to spot itThe source of a delivered message shows X-Virtual-MTA with a recognizable name.
How to do it rightReturn the default. For investigations use accounting — the vmta field is in every record and is quicker to search.

Seeing the header in a message and thinking this line is the cause

§ 3.3.7.52

What it costsThe header stays in the message even when it was not processed at all. Setting this directive changes nothing in such a situation, and the real cause is the missing permission.
How to spot itThe header is in the message, retain-x-virtual-mta is not set, and the stream in accounting is not the one in the header.
How to do it rightCheck process-x-virtual-mta in the matching source block. Both symptoms — the stream not selected and the header left in place — come from one cause here.
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
retain-x-virtual-mta <boolean>
Values
yes | no | true | false
Default
false § 3.3.7.53
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<source>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The directive lives in <source> and merges by the source rule: a narrower block overrides a wider one. During an investigation it is worth enabling in a narrow block — the subnet the submission comes from — and not in <source> 0/0, otherwise the header will stay in all of the node’s mail.
⇄

Related directives

2 relations

Does not work without

process-x-virtual-mta<source>Acts only where the header is processed at all and present in the message. § 3.3.7.53

Applies to

Headers the sender uses to control deliveryOne of the submission service headers; each has its own “process” and “keep” pair. § 3.3.7.53

How to check on the node
The quickest check is on the message itself — send it to your own mailbox and look at the source. From the configuration:
grep -n -B5 retain-x-virtual-mta /etc/pmta/config
If there is no line at all, the default no applies and the header is removed. If the header is still visible in the delivered message and this line is absent, it was not processed: check process-x-virtual-mta.
◇

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.◇Selecting a sending address by message contentRegular expressions are matched against a header, the return address or the recipient and select a sending address or assign a priority; lists can call each other.◇How a message gets into the engineSix described submission methods: extended SMTP, four language bindings and a directory the node watches on disk.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Sending address rotation · Connect a sending platform
Neighboring settings of the block <source>:process-x-virtual-mtadefault-virtual-mtareject-invalid-virtual-mtaallow-empty-x-virtual-mtaretain-x-dkim-keyAll 74 directives of the block →