Demo
Demo

Knowledge base

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

retain-x-job

<source>

Whether to keep the x-job header in the message on delivery
in the configuration this is a lineretain-x-job falseinside the block <source>
Whether to show the recipient the name of your mailing

The default is false: the engine removes the header before sending. With true it stays in the message and reaches the recipient.

The condition of applicability is named plainly here, and this is what sets the directive apart from its family neighbors: it is used only if reading the header is allowed and the header is present in the message. For the signing and schedule pairs, on the contrary, the manual stresses that the halves are independent.

The main trap is that the job label says more about you than it seems. It usually holds the mailing name, the stream number, sometimes the client identifier. Left in the message, it goes to the recipient and ends up in their mail logs and in the complaints they later send.
What the Hub does. It does not write it — and has no reason to: the Hub does not set a job label at all, and reading the header is not enabled in any source. Sources with a login have an explicit process-x-job false, the rest take the vendor default — also false. There is nothing to remove, because there is nothing to read.
Recommended values

What to set. The default is right almost always:

Value When
no (default) the usual case: the recipient has no need to see your mailing’s name
yes the message goes to your own seed mailbox, and the label needs to be seen by eye

The second case is about seeding and investigations, and it should be kept on a separate source, not on the general one.

The false default and the condition “only with reading enabled and the header present” come from the manual, § 3.3.7.51. The breakdown of cases is ours.
Example configuration
# the header stays in the message — only for your own mailboxes
<source 10.0.0.5>
    process-x-job true
    retain-x-job true</source>
Both lines are needed together: without the first the header is not read, and the second, by the letter of the section, does not apply at all. The example makes sense on a source from which messages go to your own mailboxes.
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▶

Setting retention without permission to read

§ 3.3.7.51

What it costsThe manual names the condition plainly: the directive is used only if reading is allowed and the header is present in the message. The line without its pair does nothing, and what happens to an unread header the reading section does not say; for the neighboring headers such sections write that it stays in the message.
How to spot itThe job header is visible in delivered messages, although retention is off.
How to do it rightLook at the pair as a whole: first decide whether the header is read, and only then whether it is retained.

Leaving it on in the general source

our experience

What it costsMailing names go to all recipients and end up in their logs and complaints. The structure of your campaigns becomes visible from outside.
How to spot itThe job label shows up in messages received in other people’s mailboxes.
How to do it rightKeep retention only on a separate source for your own mailboxes, and return the default on the general one.
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-job <boolean>
Values
yes | no | true | false
Default
false § 3.3.7.51
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. For submission under a login the named block applies, and the line has to be repeated in it — we did not see inheritance from address blocks into a named one on our installation.
⇄

Related directives

2 relations

Does not work without

process-x-job<source>The first half of the pair, and here it is mandatory: without permission to read the header this directive does not apply. § 3.3.7.51

Applies to

Headers the sender uses to control deliveryThe “keep or remove” half for one of the six service headers. § 3.3.7.51

How to check on the node
The setting is visible in the configuration, the consequence — in the delivered message:
grep -n 'retain-x-job' /etc/pmta/config /etc/pmta/virtualhost.txt
Empty output means the vendor default — the header is removed. The final check is possible only with a message in a seed mailbox: the engine shows the setting, not the result.
◇

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 →