Demo
Demo

Knowledge base

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

jobid-prefix

<source>

A prefix added to the job tag from the message
in the configuration this is a linejobid-prefixinside the block <source>
Outside tags stop colliding with yours

The directive prepends its value to the job tag the submitting side sent in the header. It has no default: if it is not written, there will be no prefix.

A reserved form of the prefix is named separately — {auth}. With it the prefix becomes the login the message was submitted under. The manual also gives the case it was made for: a relay service distinguishes each of its users’ mail this way without requiring anything of the users themselves.

The prefix makes sense only where a tag appears at all — that is, with reading the header allowed: process-x-job.

The main trap is that without a prefix different senders’ tags collide. The tag value is made up by the submitting side, not by you. Two clients who named their campaign the same way — campaign1, test, 2026-08 — will end up as one job: stopping one will stop the other, and selection will show someone else’s messages.

The reserved {auth} solves this without negotiating with clients, but it works only where submission goes under a login. On a source without authentication there is nothing to substitute.

What the Hub does. It does not write it — there is nothing for the prefix to be added to: reading the job header is forbidden in all submission sources, and tags do not appear.

The Hub issues submission logins one per “domain plus sending address” pair, so the reserved value would hit the target exactly here, if job tags were used at all.

Recommended values

What to set. A choice between two kinds of values:

Value When
{auth} submission goes under logins, and separation by submitter is needed
a string of your own submission comes from one login, and separation by node, site or client is needed
do not write it job tags are not used at all

The string is worth keeping short: it is prepended to every tag, and tags are later used for manual selection on the command line.

The syntax, the absence of a default and the reserved value with login substitution come from the manual, § 3.3.7.48. The advice about string length is ours.
Example configuration
# the prefix becomes the login the message was submitted under
<source 10.0.0.0/24>
    process-x-job true
    jobid-prefix {auth}</source>
A message submitted by user shop with the line “x-job: sale-08” will get a tag starting with this login. Selecting by it in the queue will show only this client’s messages.
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 a prefix without permission to read the header

§ 3.3.7.48

What it costsThe tag does not appear at all, and there is nothing to prepend to. Meanwhile the line in the configuration looks like it works.
How to spot itThe node’s job list is empty, even though a prefix is set.
How to do it rightGrant permission to read the header in the same source block.

Counting on login substitution where there is no login

§ 3.3.7.48

What it costsThe reserved value substitutes the user the message was submitted under. On a source where authentication is not required, there is nothing to substitute.
How to spot itJob tags do not differ from each other, even though the prefix is set with the reserved value.
How to do it rightEither require authentication on this source or set the prefix as a string of 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
jobid-prefix <string>
Values
a string
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. A prefix set in a wide block also goes to all narrow ones that have not named their own — here that is more useful than not.
⇄

Related directives

2 relations

Works together with

process-x-job<source>Without permission to read the header there is nothing to prepend to. § 3.3.7.48

Applies to

Headers the sender uses to control deliveryWorks on top of a tag that arrived in one of the six control headers. § 3.3.7.48

How to check on the node
The prefix is visible in the configuration, the result in the job list:
grep -n 'jobid-prefix' /etc/pmta/config /etc/pmta/virtualhost.txt
pmta show jobs --maxitems=20
Names in the job list should start with the prefix. If they do not, either the line is in the wrong source block or the tag came not in a header but in a merge variable.
◇

What else to read

3 articles

◇The source default is the bottom rung, tied to whoever connectsA source block matching the sender’s address can name a default stream; it applies when no choice was made higher up the ladder.◇How a message gets into the engineSix described submission methods: extended SMTP, four language bindings and a directory the node watches on disk.◇A license for a fleet, not for a serverThe license is not bound to a server: it is installed on as many machines as the instance limit allows, and the nodes send volume statistics to the vendor every hour.

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