Demo
Demo

Knowledge base

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

jobid-header

<source>

Which header to take the job label from instead of x-job
in the configuration this is a linejobid-headerinside the block <source>
A job label under the platform’s name

The directive names your own header in place of x-job. The point is to accept messages from a platform that already tags mailings with its own header without making it rename the header for the engine.

There is no default: if it is not written, the usual method is used.

The manual names the order of precedence directly. If the label can be taken by other means — allowed reading of x-job or the *jobId merge variable — they take precedence. The header named here works only when the higher-ranking methods produced nothing.

About the fate of the header itself the section is silent: whether it is removed before delivery, like x-job, the manual does not say, and it has no paired “retain” directive.

The main trap is that your own header name loses to the standard one. If you set up taking labels from Campaign-Id and leave x-job reading on, you will get the label from x-job every time both headers end up in a message. This will not diverge right away: while the platform sends only its own header, everything looks like it works.

The other half is the manual’s silence about whether the named header is removed. You will have to check with your own mailbox: if it reaches the recipient, your campaign name travels along with it.

What the Hub does. It does not write it: job labels play no part in the Hub’s submission, and there is nothing to rename the header for.

The directive would be useful where a Hub node accepts mail from another platform that has its own campaign header — but such submission goes under a shared login and without labels in our setup.

Recommended values

What to set. There is one value — a header name, and what you choose is not the value but whether the line is needed at all:

Value When
do not write it the submitting side can set x-job
a header name the platform already tags mailings with its own header, and it cannot be changed

If the line is needed, it is reasonable to turn off x-job reading on the same source: two methods at once produce a non-obvious precedence.

The absence of a default and the precedence of the usual method and the merge variable come from the manual, § 3.3.7.50. The manual is silent about the fate of the named header. The advice to turn off the second method is ours.
Example configuration
# the label is taken from the platform's header, the standard method is off
<source 10.0.0.0/24>
    jobid-header Campaign-Id    process-x-job false
</source>
The second line is not superfluous here: while x-job reading is on, it takes precedence — and a message with both headers will get its label from x-job.
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▶

Leaving both methods enabled

§ 3.3.7.50

What it costsWhen both headers are in the message, the standard one wins, and the label will not be the one the platform puts in. The behavior depends on what exactly came in the message — that is, it changes from mailing to mailing.
How to spot itJob labels are sometimes right and sometimes someone else’s, with no visible pattern.
How to do it rightKeep one method per source: either the standard header or the one named by this line.

Expecting the named header to be removed automatically

§ 3.3.7.50

What it costsThe manual is silent about this, and there is no paired “retain” directive. If the header reaches the recipient, the campaign name leaves along with the message.
How to spot itThe platform’s header is visible in a message received in the seed mailbox.
How to do it rightCheck with your own mailbox and, if necessary, clean out the header with the remove-header directive on the same source.
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
jobid-header <header-name>
Values
a header name
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. A header name set in a broad block also goes to narrow ones that have not named their own.
⇄

Related directives

2 relations

Can be replaced by

process-x-job<source>The standard method, and it takes precedence: while it is on, it wins. § 3.3.7.50

Applies to

Headers the sender uses to control deliveryA variant of the same mechanism: the label comes in a header, only the header name is your own. § 3.3.7.50

How to check on the node
The line is visible in the configuration, the result — in the job list:
grep -n 'jobid-header\|process-x-job' /etc/pmta/config /etc/pmta/virtualhost.txt
pmta show jobs --maxitems=20
If the labels in the list are not the ones the platform puts into its header, most likely the higher-ranking method fired. Whether the named header is removed before delivery can be learned only with a message to your own mailbox: the manual does not say.
◇

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 →