Demo
Demo

Knowledge base

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

process-x-virtual-mta

<source>criticalset by the Hub

Whether to read the X-Virtual-MTA header and select the stream by it
in the configuration this is a lineprocess-x-virtual-mta falseinside the block <source>
A permission without which the header is useless

The default is false, and the manual’s advice is direct: enable it for the sources you submit mail from if you want the header to select the stream.

Without the permission the miss is twofold. The selection does not work — the message leaves through whatever is assigned lower on the ladder. And the header itself stays in the message and reaches the recipient, showing them the fleet’s internal names. Stripping the header is part of the processing, not a separate action.

The permission is granted to the source as a whole. The engine cannot restrict the set of streams this sender is allowed to name.

The main trap. The permission is not limited to a list of streams: by granting it, you have allowed naming any stream on the node — including one being warmed up for another client. The only boundary here is not granting the permission at all.
What the Hub does. It writes yes itself — in every source of the working configuration: both in those selected by address and in the named login-based submission sources. Otherwise warm-up could not name the address: the plan puts the header on every message, and this is the main way of selecting a stream in the Hub. Client separation rests not on this line but on submission going through the Hub under its own logins.
Recommended values

What to set. The answer depends on exactly one thing — whether you trust the source:

Value When
yes submission comes from us: the scheduler, a platform under our control
no (default) someone else’s submission that must not be given the choice of address

There is no middle option. If an outside sender does need a choice, give it with a pattern rule in <pattern-list>, where you, not they, define the “sender → stream” mapping.

The false default and the advice to enable it for submission sources come from the manual. The “whom to grant it to” breakdown is ours.
Example configuration
# the permission is granted to the source the submission address falls under
<source 10.0.0.0/24>
    process-x-virtual-mta yes    always-allow-relaying yes
</source>
A message from this subnet with the line x-virtual-mta: shop-example-com leaves through the named stream, and the header itself is stripped before delivery. Without the permission line, the same header does nothing and travels to the 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 ends3 mistakes▶

Granting the permission to the wrong source

§ 3.3.7.52

What it costsA node usually has several <source> blocks, and the one the submitter’s address falls under is selected. A permission in another block does nothing: the stream is taken from the default, and the header travels to the recipient.
How to spot itThe delivered message shows X-Virtual-MTA, while accounting has a different stream name.
How to do it rightFind the narrowest <source> block the submission address falls under and put the permission there.

Granting the permission to an outside source

§ 9.4.1

What it costsThe sender gets the right to name any stream on the node. Someone else’s campaign may leave from an address being warmed up and burn its reputation.
How to spot itIn accounting, one sender shows another sender’s stream names.
How to do it rightKeep the no default and set the selection for this sender with a pattern rule — then you define the mapping.

Enabling the header without deciding what to do with a typo

§ 3.3.1.55.2

What it costsA name that does not exist on the node means a rejection at submission by default. Renaming a stream — a routine matter during rotation — turns every message with the old name into a rejected one.
How to spot itThe platform reports submission rejections right after stream names change in the configuration.
How to do it rightSolve it with the pair invalid-virtual-mta-fallback and reject-invalid-virtual-mta — both are needed together, neither works on its own.
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
process-x-virtual-mta <boolean>
Values
yes | no | true | false
Default
false § 3.3.7.52
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. A permission granted in <source> 0/0 also applies to all subnets for which nothing to the contrary is said — which means that “grant it only to our own” means no in the wide block and yes in the narrow one, not the other way around.
⇄

Related directives

4 relations

Works together with

invalid-virtual-mta-fallbackGlobalDecides what to do with a message if the stream named in the header is not declared on the node. § 3.3.1.55.2allow-empty-x-virtual-mta<source>Answers the neighboring question: whether an empty header value counts as acceptable. § 3.3.7.67

Can be replaced by

default-virtual-mta<source>The source default ranks below the header and applies when there is no header. § 3.3.7.32

Applies to

Headers the sender uses to control deliveryOne of the submission control headers: each is allowed separately and per source. § 3.3.7.52

Referenced from

retain-x-virtual-mta<source>Acts only where the header is processed at all and present in the message. § 3.3.7.53reject-invalid-virtual-mta<source>A wrong name usually arrives in a header — which means the question arises where the header is allowed. § 3.3.7.34Selecting a sending address by message contentA step above: the message header is stronger than a pattern rule. § 3.3.7.52The stream is named by a header, if the source is allowed to do soThe permission without which the header does not work: it will not select a stream and will stay in the message. § 9.4.1

How to check on the node
The permission is checked in the configuration — the node does not show it separately:
grep -n -B5 process-x-virtual-mta /etc/pmta/config
The block found must be the one the submission address falls under, and the narrowest of the matching ones. Whether the permission worked is checked in accounting: if the vmta field has a name different from the one in the header, the block is the wrong one.
◇

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
Managed at
Infrastructure → Sending addresses
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 · Connect a sending platform
Priority
critical
Neighboring settings of the block <source>:default-virtual-mtareject-invalid-virtual-mtaretain-x-virtual-mtaallow-empty-x-virtual-mtaretain-x-dkim-keyAll 74 directives of the block →