Demo
Demo

Knowledge base

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

process-x-job

<source>set by the Hub

Whether to read the x-job header and tag the message with it
in the configuration this is a lineprocess-x-job falseinside the block <source>
The permission without which a mailing cannot be singled out later

The default is false. With the permission, the engine takes the value of the x-job header and makes it the message’s job tag. The header looks simple:

x-job: abc123

The restriction on the value is strict: printable characters, no spaces or non-printable characters. A message is expected to have one such header.

The header does not work with merging. If a message is assembled by merging, the tag is set with the *jobid variable, not with the header — the manual says so directly.

What it is all for: the job tag is the only thing on a node that lets you single out your own mail among other people’s. –jobId for listing, deleting and changing priority relies on it, and so do stopping and resuming a single mailing.

The main trap is that the tag cannot be set retroactively. The permission applies to messages submitted after it. The moment the tag is needed is the moment one mailing out of several has to be stopped urgently, while its messages are already in the queue and already untagged.

The second half: without the permission the header will not work and there will be no error. The platform will keep setting it, the node will keep ignoring it, and the discrepancy will surface only when someone tries to use the tag.

What the Hub does. It writes it — and writes a prohibition: the line process-x-job false is in every named submission source of the working configuration.

This is also why queue management in the Hub works the way it does: stopping, resuming and deleting work per queue, not per job. There is nothing to select by job — neither warm-up nor the submission platform sets the tag.

On a node carrying mailings from several senders, this means that a stop affects everyone sending in the same direction.

Recommended values

What to set. The answer depends on who is responsible for the tag’s contents:

Value When
no (default) the submission is someone else’s, and there is no reason to let it name job tags
yes the submission is yours, and you want to be able to stop mailings one by one

The jobid-prefix prefix removes half of the objections to yes: it adds your value to the tag, and jobs from different senders can no longer collide. With the {auth} value the prefix becomes the submitter’s login.

The false default, the character restriction, and the caveats about a single header and about merging come from the manual, § 3.3.7.49. The “who to grant it to” breakdown is ours.
Example configuration
# the permission is granted to the source that submission falls under
<source 10.0.0.0/24>
    process-x-job true    jobid-prefix {auth}
</source>
A message with the line “x-job: sale-08” will get a tag starting with the login of the submitting user. From there this tag is used for selecting in the queue and for stopping a single mailing.
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 ends3 mistakes▶

Putting spaces or a human-readable name in the tag

§ 3.3.7.49

What it costsThe manual allows only printable characters without spaces. A readable mailing name does not fit this, and the tag is either not set or set to something other than intended.
How to spot itThe node’s job list is empty or shows truncated names.
How to do it rightUse a machine identifier for the mailing, and keep the human-readable name on your side next to it.

Setting the header in a message assembled by merging

§ 3.3.7.49

What it costsFor merging the manual requires the *jobid variable and directly says not to use the header. The tag will not be set, and the mailing will be indistinguishable from the others.
How to spot itJobs are visible for regular mailings and not visible for merged ones.
How to do it rightIn merging, set the tag with the *jobid variable.

Granting the permission to someone else's source without a prefix

our experience

What it costsThe other sender names job tags itself — and may choose the same ones as you. Stopping your mailing will also affect its messages, and stopping its mailing will affect yours.
How to spot itThe job list contains names your platform did not set.
How to do it rightAdd a prefix — with your own value or the reserved {auth}, which substitutes the submitter’s login.
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
process-x-job <boolean>
Values
yes | no | true | false
Default
false § 3.3.7.49
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 the address blocks that cover it, and the narrow one overrides the wide one. For submission under a login the named block applies — in our configuration the prohibition is written exactly there, in each submission block separately.
⇄

Related directives

3 relations

Works together with

jobid-prefix<source>The prefix is prepended to the value from the header and keeps jobs from different senders apart. § 3.3.7.48

Can be replaced by

jobid-header<source>The same result with a different header; with the permission on, x-job wins. § 3.3.7.50

Applies to

Headers the sender uses to control deliveryOne of the six submission control headers, with its own permission on the source. § 3.3.7.49

Referenced from

retain-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.51track-jobs<domain>The job identifier comes from there — without it there is nothing to break the queue down by. § 3.3.10.105

How to check on the node
The permission is visible in the configuration, the result in the node’s job list:
grep -n 'process-x-job\|jobid-' /etc/pmta/config /etc/pmta/virtualhost.txt
pmta show jobs --maxitems=20
An empty job list with a non-empty queue means that nobody sets the tag: either there is no permission, or the submitting side does not send the header. Ours is always empty — the permission is turned off on purpose.
◇

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
Value
The Hub picks it itself — pace, warm-up stage, metrics
Cost of a mistake
reversible: harms only while it is set
Scenarios
Connect a sending platform
Neighboring settings of the block <source>:jobid-prefixallow-mailmergeadd-date-headeradd-message-id-headeradd-received-headerAll 74 directives of the block →