Demo
Demo

Knowledge base

PMTA knowledge base›Procedure§ 4.2.2

Figure out why a queue to one receiver is growing

Troubleshooting Email Delivery Problems
Three circles, widening from simple to expensive

The manual starts from the fact that delivery failure is normal, not an incident: invalid addresses, network glitches and misconfigured receivers are expected, and retries exist precisely for them.

It is worth investigating when mail piles up to one specific receiver. That is the sign that distinguishes a problem from ordinary noise.

The first circle is route and reachability. One command resolves the receiver’s name and connects to its mail hosts. Whichever half failed names the cause: the name did not resolve — it is a DNS question; the connection failed — a question for the network or the receiver.

The second circle is making the node try. The command triggers an immediate delivery attempt with the session written to the log: it will contain the receiver’s real responses, not our guesses about them.

The third circle is observation. If the problem is intermittent, a block with connection and command logging enabled is created for the receiver, and removed as soon as the answer is obtained. This is the most expensive step: the log grows fast.

The main trap is leaving logging on. The third circle enables recording of every step of the conversation with the receiver. While the investigation is going on, it is invaluable; forgotten, it is a file growing faster than the spool, and rotation eating up history in hours instead of days. The next time the log is needed, the day you want will no longer be in it.
What the Hub does. It does not do this — it calls none of these commands, and in the configuration templates connection, command and data logging is turned off, and there are no receiver blocks with logging enabled.

That is, in our setup the first and second circles are available only by hand, by logging into the node. Telemetry shows what is happening — the queue is growing, the bounces are such and such — but not why: it does not contain the receiver’s real responses, only their parsed category.

This is a deliberate boundary: logging on every fleet node would be expensive. But when an investigation is needed, you have to go to the node manually.

Recommended values

Three circles and the cost of each:

Circle What it does Cost
route and reachability one command, reads DNS and connects nothing
attempt with logging one message, the session in the log one delivery
per-receiver logging writes every step of the conversation grows fast, remove right away

Start with the first and do not skip circles. Half the cases are explained already at the first: the name does not resolve or the host does not respond. There is no point going further.

Set up the third circle with the intention of removing it. A good habit is to create it together with a reminder, not “until it is figured out.”

The analysis of each circle’s cost and the advice about a reminder are ours. From the manual here come the sequence of the three steps itself, the “failure is normal, a pile-up at one receiver is a reason” framing and the instruction to remove logging after getting the answer.
Example configuration
# three circles in order
pmta resolve gmail.com --connect
pmta trace gmail.com --to-log# the third circle — a block with logging, and remove it right after
The highlighted line is the step the investigation is usually started for: the node tries to deliver a message right now, and the whole session with the receiver’s responses goes into the log.
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▶

Leaving logging on after the investigation

§ 4.2.2

What it costsThe third circle writes a line for every step of the conversation with the receiver. Forgotten, it bloats the log and shortens history to hours — and the next time the day you need will no longer be there.
How to spot itThe log directory is noticeably larger than usual, and history is shorter than a day.
How to do it rightRemove the block right after getting the answer. Create it together with a reminder, not “until it is figured out.”

Starting with a trace and skipping the first circle

§ 4.2.2

What it costsHalf the cases are explained by checking the route and reachability: the name does not resolve or the host does not respond. In these cases a trace will show the same thing, only more expensively and later.
How to spot itThe trace does not connect, and the investigation starts over with the DNS question.
How to do it rightGo through the circles in order. The first is free and answers more often than the others.

Looking for the receiver's response in the command's output

§ 4.2.2

What it costsThe trace writes the session to the node’s log rather than printing it. The command’s empty output is taken as no result, and the command is repeated again.
How to spot itThe command finished, and nothing meaningful is on the screen.
How to do it rightRead the log right after the call — the session is there.
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

6 relations

Does not work without

Resolve a name and connectThe first circle: resolves the receiver’s name and connects to its mail hosts. § 4.2.2Delivery attempt with the session loggedThe second circle: an immediate delivery attempt with the session logged. § 4.2.2log-connections<source>The third circle: logging connections, enabled for a specific receiver and removed right away. § 4.2.2log-commands<source>The third circle: logging the conversation’s commands — the most expensive investigation step. § 4.2.2

Affects

Backoff mode — the queue's second personalityThe same accumulation of refusals moves the queue into backoff mode — worth checking the mode before looking for the cause further. inference

Where you can see it

The node's own logBoth the trace and per-receiver logging write exactly here, not to the command’s output. § 4.2.2

Referenced from

What the node tells about itself and through which channelsInvestigating a single receiver is exactly choosing between these surfaces in order. § 4.1.1Return a node fileThe investigation in which this output is one of the steps. inferenceThe name lookup did not complete — and no conclusion is drawnThe failure the very first investigation circle names: the receiver’s name did not resolve. § 5.8

How to check on the node
The investigation result is read in the log, not in the command’s output:
pmta resolve gmail.com --connect
pmta trace gmail.com --to-log && tail -n 100 /var/log/pmta/log
pmta show queues gmail.com
The second command writes the session to the log — it does not print details itself. The third shows what is happening with the queue to this receiver: whether it is still piling up after the cause was found.
◇

What else to read

3 articles

◇What the node tells about itself and through which channelsSeven observation surfaces: the web monitor, the console in four formats, the log, accounting, accounting search, metrics and export to external analytics.◇The watchdog that restarts the engineKeeps an eye on the engine and brings it back up after a crash by itself, sending a crash report to the postmaster address.◇How the policy for a receiver is assembledSettings are assembled from the most general pattern to the most precise; the order of blocks in the file means nothing.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Troubleshoot deliverability · Tune the pace for a provider · Untangle a stuck queue