Demo
Demo

Knowledge base

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

allow-mailmerge

<source>

Whether merge extensions can be used from this source
in the configuration this is a lineallow-mailmerge falseinside the block <source>
Permission to submit one message for many

The default is false. The line allows the source to use merge extensions — three additional protocol commands with which a message is transferred once, while the recipients and substituted values go separately.

The point is volume: one transfer instead of a thousand identical ones, and the difference in load on the channel and the node is noticeable.

The line can be enabled indirectly. The manual says: always-allow-api-submission set to yes is currently equivalent to this permission. That is, by enabling the permission for API submission, you have enabled merging too.

The main trap is enabling it without noticing. The API submission permission enables merging along the way, and this line is not in the configuration at all. Reading the source block, you will not see that merging is allowed; you can learn about it only from the manual or from the behavior.

The other half: merging has its own handling of control headers. The job label there is set with a variable, not a header — and the same goes for the date.

What the Hub does. It does not write it — and does not enable it indirectly either: always-allow-api-submission, which by the letter of the manual is currently equivalent to the merge permission, was removed from the configuration on August 29, 2026.

We do not need merging anyway: warm-up submits messages one at a time over regular SMTP, and the Hub does not use API submission.

Recommended values

What to set. The permission is worth granting when needed, not in advance:

Value When
false (default) submission goes one message at a time — our case
true the submitting platform can merge and the volume is worth it

It is not only this line that needs checking: the API submission permission enables merging by itself.

The false default comes from the manual, § 3.3.7.11. Equivalence to the API submission permission — § 3.3.7.72, as is the word “currently.”
Example configuration
# the permission is granted to the source whose platform can merge
<source 10.0.0.0/24>
    allow-mailmerge true</source>
The same setting is enabled by always-allow-api-submission yes — and enabled silently, without this line in the configuration.
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▶

Assuming merging is off because the line is absent

§ 3.3.7.72

What it costsThe API submission permission enables it by itself. A source that has only that permission accepts merge commands — and this is not visible when reading the block.
How to spot itThe receiver’s greeting shows merge extensions, although there is no permission line in the configuration.
How to do it rightCheck both lines and, if merging is not needed, reconsider the API submission permission.

Expecting the usual header handling from merging

§ 3.3.7.1

What it costsMerging has its own rules: the job label is set with a variable, not a header, and automatic date addition is not supported for it at all.
How to spot itMessages assembled by merging have no job label or date, although the corresponding lines are enabled.
How to do it rightSet both with merge variables.
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
allow-mailmerge <boolean>
Values
yes | no | true | false
Default
false § 3.3.7.11
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 follows source merging: a connection falls under all address blocks that cover it, and a narrow one overrides a broad one. On top of that comes indirect enabling: the API submission permission in any of the merged blocks enables merging too.
⇄

Related directives

2 relations

Works together with

mailmerge-expands-undefined-variablesGlobalDecides what to do with a variable for which no value was passed. § 3.3.1.39

Affects

always-allow-api-submission<source>Enables this permission along the way — by the letter of the manual, it “is currently equivalent.” § 3.3.7.72

Referenced from

What the submitting system assembles before sendingMerging also has to be allowed in the submission block — otherwise the submitting system will not apply it. § 7.1Personalization inside the enginePermission on the node: without it the submitting system will not apply merging. § 7.1What the submission bindings needThe directive that enables this mechanism. § 7.1Mail merge via SMTP extensionsThe directive that enables this mechanism. § 11.19.3

How to check on the node
You need to look at both lines — the second enables the first:
grep -n 'allow-mailmerge\|always-allow-api-submission' /etc/pmta/config /etc/pmta/virtualhost.txt
printf 'EHLO test\r\nQUIT\r\n' | nc <node-address> 2525 | grep -i xmrg
The absence of the first line does not mean merging is off: the second enables it by itself. It is more reliable to look at the receiver’s greeting from the submission address.
◇

What else to read

3 articles

◇How a message gets into the engineSix described submission methods: extended SMTP, four language bindings and a directory the node watches on disk.◇Who is allowed to submit mail and for whom to accept itOut of the box, the node accepts submission only from the machine itself; two different questions — “who can send through us” and “for whose addresses we accept mail” — are answered by different directives.◇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.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Connect a sending platform
Neighboring settings of the block <source>:process-x-jobjobid-prefixbccadd-message-id-headeradd-received-headerAll 74 directives of the block →