Demo
Demo

Knowledge base

PMTA knowledge base›Mechanism§ 9.4

The merge variable is the top rung, and it lives in the content

vmta merge variable
Stream selection hidden inside the message itself

It is available for submission via the API, for batch submission from a directory and over SMTP wherever merging is enabled. It sits at the top of the precedence order — which means it is the only selection method that cannot be overridden by a node setting.

And at the same time the least noticeable of the six. A header is visible in the message, an API call in the submission log, a rule in the configuration. A merge variable lies in the content data, where people look last when investigating an incident.

Its granularity is its own. A header and a method call act on the whole merge job; a variable acts per recipient, because merge data is recipient data.

The main trap. If the node accepts someone else’s content and merging is allowed, the sender chooses its stream itself — whatever is written in the configuration. For a platform with several clients this means a client can move onto someone else’s address under warm-up, and no source setting will prevent it.
What the Hub does. It does not use it: warm-up names the stream with a header, which is simpler and more visible. What is worth keeping in mind is the reverse — as a risk. Merging is allowed by a source directive, and that same decision determines whether content can override our assignment. As long as the Hub does not enable merging, there is no risk; when enabling it for some platform, remember that along with the convenience you hand over the choice of address.
Recommended values

The mechanism has no values of its own: the value is a stream or pool name in the merge data. On the node side only one thing is configured — whether merging is allowed for this source at all (allow-mailmerge). There are no intermediate modes: you cannot allow merging and forbid stream selection through it.

From the manual here comes the fact that the variable ranks above everything and works on three submission paths. The risk assessment for a multi-client node is ours.
Example configuration
# merging is allowed — and with it the sender gets the top rung
<source 10.0.0.0/24>
    allow-mailmerge yes    process-x-virtual-mta yes
    default-virtual-mta mta-hub-pool
</source>
Both lower lines no longer guarantee anything for this source: a merge variable in the content will override both the header and the default. If stream selection must stay with the node, merging is not granted to such a source.
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▶

Allowing merging for a source with someone else's content

§ 9.4

What it costsTogether with merging, the sender gets the right to choose any stream on the node, including one under warm-up for another client. The configuration looks correct and violates nothing.
How to spot itA client’s accounting shows stream names that were never assigned to it; a neighbor’s daily warm-up volumes grow for no reason.
How to do it rightDo not grant allow-mailmerge to sources with someone else’s content. The only protection here is not enabling it: the engine cannot restrict the choice to “only these streams.”

Looking for the cause in the configuration

§ 9.4

What it costsThe investigation goes through the configuration from top to bottom and finds nothing, because the cause lies above the configuration — in the message content. Time is spent checking rules that were not even read in this case.
How to spot it“The configuration is all correct, but messages go out from the wrong address” — round and round.
How to do it rightStart the investigation with the question “is merging enabled for this source.” If yes, the configuration need not be examined until the content is ruled out.
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.
Inheritance
The mechanism has no inheritance: the variable is parsed in each message. What is inherited is the permission — allow-mailmerge is written in <source> and merges by the source rule: a narrower block overrides a wider one.
⇄

Related entries

1 relation

Depends on

Personalization inside the engineIt exists only where merging is enabled, and for the same reason it acts per recipient. § 9.4

How to check on the node
There is no separate counter. Indirectly — by a mismatch between what was assigned and the stream name field in accounting:
pmtaacctfind --output csv[vmta,jobId,rcpt] /var/log/pmta/acct-*.csv
If the stream differs from the assigned one while the header was correct, exactly one cause remains higher up the ladder — a merge variable in the content. Check on the sender’s side; there are no traces on the node.
◇

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