Demo
Demo

Knowledge base

PMTA knowledge base›API endpoint§ 5.10

Jobs

/jobs
A breakdown by campaign

Returns jobs — groups of messages — with the number of recipients and volume in the queue.

The call is GET /jobs?format=json (or xml), one job — GET /jobDetail?format=json&jobid=123.

This is the “Top jobs” top: the length is set by http-default-max-items, ten lines by default.

The job is assigned to a message by the submitting side. Over SMTP this is the X-Job header, and it is read only if process-x-job is allowed for the source — by default it is not. With mail merge, the job is set with the *jobid variable, not a header.

Access is decided by http-access based on the address the request came from — the monitor level is enough for reading. The key from http-api-key in the X-API-Key header grants full access from any address.

The main trap is taking an empty response for no campaigns. Jobs are formed only from messages to which the submitting side assigned a job and for which the source allowed assigning it. An empty response with a full queue more often means “jobs were not assigned” than “nothing to send”.
What the Hub does. It asks — the “PMTA monitoring” screen takes this endpoint together with the other four. But in the named login sources the Hub writes process-x-job false, so mail submitted through node logins does not form jobs, and there are no jobs for it on the screen.
Recommended values

What to ask this endpoint:

Question This one or not
which campaigns are in the queue now yes, if jobs are assigned
one job in full yes — /jobDetail
all jobs, not the top no — show jobs: the command defaults to “all”
what happened yesterday no — that is accounting
The /jobs and /jobDetail addresses, the list length, the X-Job header with the false default and the *jobid variable come from the manual (§ 5.10, § 3.3.1.58.23, § 3.3.7.49, § 6.3.15). The split of questions is ours.
Example configuration
# jobs in the queue and one job
curl -s 'http://127.0.0.1:8080/jobs?format=json'curl -s 'http://127.0.0.1:8080/jobDetail?format=json&jobid=123'
jobid is the value the submitting side passed in the X-Job header or a merge variable.
yellow — — directive names, blue — blocks. They are highlighted the same way in the text of the card.
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

1 relation

Can be replaced by

JobsThe screen that shows the same thing to a human. § 5.10

How to check on the node
If there are no jobs, check whether their header is allowed:
curl -s 'http://127.0.0.1:8080/jobs?format=json' | head -40
pmta show jobs
grep -rn 'process-x-job' /etc/pmta/
An empty response with a full queue — first check whether the job header is allowed in the source the submission went through.
◇

What else to read

3 articles

◇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.◇Address lists — named and unnamedA list of addresses, domains, patterns or hashes; a named one is attached by directives such as suppression, an unnamed one lives inside an inbound mail processor.

In the Hub
Cost of a mistake
safe: a wrong value breaks nothing
Scenarios
Sender isolation