Demo
Demo

Knowledge base

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

replace-message-id-header

<source>

Whether to replace the message identifier set by the sender
in the configuration this is a linereplace-message-id-header falseinside the block <source>
Replacing someone else’s identifier with your own

The default is false. With true the engine replaces the existing Message-Id with its own. If the message has no such header, the line does nothing — adding one is a different directive, add-message-id-header.

The uniqueness of the new value across servers rests on the same host-id as when adding.

The main trap is that the identifier is the thread back to the sending. By it the submitting platform links a complaint, a bounce or a reply to a specific message in its database. By replacing it on the node you cut that thread: the platform knows one identifier, the recipient and the receiver see another, and there is nothing to match them by.

This does not surface at once — only at the moment a complaint arrives and someone tries to find the message by it.

What the Hub does. It does not write it — and should not. The sending library sets its own Message-Id, and the Hub saves it together with the send record. Replacing it on the node would leave us with an identifier nobody else has.
Recommended values

What to set. The case for true is narrow:

Value When
false (default) almost always: the sender’s identifier is its thread to the message
true the submitting platform sets identifiers that repeat or contain too much about your infrastructure

The second happens with old platforms that put the internal server name into the identifier. But even there it is more honest to reach an agreement with the platform than to cut the link between its database and the delivered message.

The false default and the caveat “does not act on a message without the header” come from the manual, § 3.3.7.5. Uniqueness via the node number — § 3.3.1.33. The analysis of the lost link is ours.
Example configuration
# replacement makes sense only together with an explicit node number
host-id 7

<source 10.0.0.0/24>
    replace-message-id-header true</source>
A message from this subnet will go out with the identifier assigned by the node, not by the submitting platform. The platform’s database will keep the old one — and there will be nothing to link them.
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▶

Enabling replacement on the whole node

our experience

What it costsIdentifiers lose their link to the submitting platform’s database. A complaint, bounce or reply arrives with an identifier the platform does not have, and finding the message by it is impossible.
How to spot itIdentifiers in complaints are not found in the send database.
How to do it rightKeep the default, and if replacement is still needed, enable it only for the source it was meant for.

Expecting replacement to add a missing header

§ 3.3.7.5

What it costsThe line has no effect at all on a message without an identifier. Messages keep going out without one — with the consequences at receivers that adding is enabled to avoid.
How to spot itSome messages still have no identifier, even though replacement is on.
How to do it rightAdding and replacing are different lines; you need both if the goal is for every message to have an identifier and for it to be your 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
replace-message-id-header <boolean>
Values
yes | no | true | false
Default
false § 3.3.7.5
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 obeys source merging: a connection falls under all address blocks that cover it, and the narrow one overrides the wide one. Enabling it in a wide block is dangerous: the replacement will also hit the submission whose identifier was meaningful.
⇄

Related directives

1 relation

Works together with

add-message-id-header<source>A neighboring question: that one adds a missing identifier, this one rewrites an existing one. § 3.3.7.5

How to check on the node
The setting is visible in the configuration, the consequence — in a seed mailbox:
grep -n 'replace-message-id-header\|^host-id' /etc/pmta/config /etc/pmta/virtualhost.txt
Check on a message that already had an identifier: compare what left the submitting side and what reached the mailbox. They match — the line did not trigger; they differ — it did.
◇

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-prefixallow-mailmergeadd-message-id-headeradd-received-headerAll 74 directives of the block →