Demo
Demo

Knowledge base

PMTA knowledge base›Mechanism§ 7.4.8

Two tags the sender puts on a message

critical

job id and envelope id
What is not tagged at submission cannot be selected later

A job tag declares a message part of a common campaign. There is one strict restriction: printable characters without spaces. An envelope identifier identifies one specific message.

The submitting side sets both — with a header, a merge variable or a submission library call. The node does not make them up.

Both come back in chapter 6 as command-line selectors: –jobId and –envId are understood by queue listing, deletion and priority change. The job tag can do more — pause job and resume job rest on it, that is, stopping one campaign without stopping the rest.

Hence the whole importance of the mechanism. Nothing on the node can group mail by sender unless the sender said so at submission. A platform that does not set the tag will not later be able to stop, list or delete its own mail separately — all that remains are per-queue commands, and they hit the messages of all senders going the same way.

The manual stipulates separately: deletion requires an explicit –queue or –jobId, so that a stray command does not wipe out the whole queue.

The main trap is that the tag cannot be set after the fact. It appears at submission or not at all. The realization that you cannot do without it usually comes at the moment one campaign out of four has to be stopped urgently — and by then the messages are already in the queue without tags.
What the Hub does. It does not set a job tag and forbids the header with it: every named submission source has a process-x-job false line. No envelope identifier is set either.

Hence the design of queue control in the Hub: pausing, resuming and deleting work per queue — pause queue, resume queue, delete –queue=. There is nothing to select by job.

On a node where campaigns from several senders go into the same receiver queues, this means a stop hits all of them.

Example configuration
# the tag arrives in a header, if the source is allowed to read it
<source 10.0.0.0/24>
    process-x-job true    jobid-prefix customer1
</source>
A message with the header “x-job: sale-2026-08” will get the tag customer1sale-2026-08 — the source prefix plus the value from the message. From then on this tag is understood by command-line selectors and job pausing.
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▶

Stopping a campaign with a per-queue command

§ 6.3

What it costsA queue on the node is shared by all senders going that way. Stopping per queue also delays other senders’ messages, and later nobody will link the cause of the delay in someone else’s campaign to your action.
How to spot itAfter stopping one campaign, messages unrelated to it got stuck.
How to do it rightSet a job tag at submission — then a campaign is stopped, not a direction.

Putting spaces in the tag

§ 7.4.8

What it costsThe manual allows only printable characters without spaces. A human-readable campaign name — “Summer Sale” — does not fit this restriction.
How to spot itThe tag is not set, or is set truncated.
How to do it rightUse a machine identifier for the campaign, and keep the human-readable name on your side next to it.

Deleting without an explicit selector

§ 6.3.28

What it costsThe engine deliberately requires an explicit –queue or –jobId precisely because deletion defaults to the entire queue. Deleted messages cannot be restored.
How to spot itThe delete command is rejected by the engine — or, worse, accepted with a wider selection than intended.
How to do it rightAlways name the selector explicitly, and first look with the same selector using the listing command.
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.
⇄

Related entries

4 relations

Does not work without

Pause a jobStopping one campaign is possible exactly when the messages carry a job tag. § 7.4.8

Can be replaced by

Headers the sender uses to control deliveryOne way to set the tag is a message control header, and it has to be allowed for the source. inference

Where you can see it

The list of recipients in a queueQueue listing can select by both tags. § 6.3.29Delete messages from the queueDeletion selects by both tags and requires an explicit selector. § 6.3.24

Referenced from

Seeding campaigns with control addressesA job ID is a mandatory condition: without it the campaign does not exist, and there is nothing to seed. § 11.2custom-message-id-header<signals>One more message identifier, only for the other side. inferenceReserved merge variable namesA related mechanism: they work together. § 11.19.4.2Submitting a message by writing a file into a directoryBoth tags have a header form, so file submission can set them too. § 11.20ReceivedIdentifiers the submitting side assigns to a message at submission. § 12.2.5Job headerA related mechanism: they work together. § 13.8

How to check on the node
The node shows which jobs are currently in the queue with a separate command:
pmta show jobs --maxitems=20
pmta list --jobId=<tag> --maxitems=20
An empty list means not “the queue is empty” but “nobody sets the tag”: there are messages in the queue, but none is assigned to a job. For us the list is always empty — the Hub does not set the tag.
◇

What else to read

3 articles

◇How to name a queue in a commandHow to name a queue in a command argument: the same “receiving server and sending address” pair with asterisks added.◇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.◇How the node selects a source and combines its settingsA connection falls under all source blocks whose addresses cover it, and they act merged — the narrow one overrides the wide one; named blocks are attached only by direct reference.

In the Hub
Cost of a mistake
safe: a wrong value breaks nothing
Scenarios
Emergency stop · Sender isolation
Priority
critical