Demo
Demo

Knowledge base

PMTA knowledge base›Mechanism§ 3.3.10.60

Five ways for a queue to hand off a message

queue type
A queue is not always sending out

By default a queue does what is expected of a mail node: it opens an SMTP connection and hands the message to the receiver. But that is only one of five ways, and the other four turn the queue into a processing tool rather than a sending one.

file — each message goes into a file (or is appended to a shared one). pipe — a program is run for each recipient, and the message is fed to its input. http-delivery — the message goes out as a POST request to the given address as a JSON object. discard — the message is thrown away, but an accounting record appears.

The settings of the types do not interfere with each other. The manual says plainly: lines of the discard section are ignored in queues of another type, and the same for the pipe section. A leftover line from a previous type will break nothing — but will do nothing either.

The main trap is changing the type of a non-empty queue. The manual warns in a separate line: if there are messages in the queue, changing the type requires restarting PowerMTA. A pmta reload alone is not enough, yet it looks as if the setting took effect.
What the Hub does. It uses only plain SMTP: all the queues it describes send mail out. The incoming flow — bounces, complaints, messages to role addresses — the node handles not with queues of a special type but with its bounce and complaint processors: what is recognized becomes accounting records and goes to the Hub by webhook, what is not recognized is discarded.
Example configuration
# four types side by side: sending, file, program, webhook
<domain gmail.com>
    type smtp</domain>

<domain bounces.example.com>
    type pipe    command "/opt/bounce/parse --envid \"$envid\" \"$user\""
</domain>

<domain archive.example.com>
    type file    file-destination /var/spool/archive/
</domain>

<domain feedback.example.com>
    type http-delivery    http-delivery-url https://hub.example.com/api/v1/feedback
</domain>
The type is set for a receiver, not for the node: one node can easily run queues of all five types at once.
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▶

Changing the type of a queue that holds messages

§ 3.3.10.60

What it costsA configuration reload is not enough: the manual requires a service restart. The setting looks applied, but the queue works the old way.
How to spot itpmta show settings prints the previous type, although the configuration has the new one.
How to do it rightWait for the queue to empty, or restart the service.

Expecting one type's settings to affect another

§ 3.3.10.109

What it costsLines of the discard and pipe sections are ignored in a queue of another type. There will be no error, but no effect either.
How to spot itThe line is set and appears in the settings output, yet behavior does not change.
How to do it rightMatch the line against the queue type: each type has its own set.
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

2 relations

Can be replaced by

A fake receiver inside the node itselfTwo ways to absorb test traffic: a stub queue on our side or a fake receiver on someone else’s. inference

Affects

discard-as-bounce<domain>Decides what a discarded message counts as in accounting — a delivery or a bounce. § 3.3.10.109.1

Referenced from

disable-acct-records<domain>Discarding is the delivery type for which the line is most often added. § 3.3.10.8type<domain>The mechanism as a whole: what each of the five types does and which lines go with it. § 3.3.10.60file-format<domain>The line works only for a queue that writes to a file; in a queue of another type it is ignored. § 3.3.10.110.1file-destination<domain>The line works only for a queue that writes to a file; in a queue of another type it is ignored. § 3.3.10.110.2command<domain>The line is mandatory for a queue that hands messages to a program; in a queue of another type it is ignored. § 3.3.10.111.1macro-variables-preserve-case<domain>A line from the set of the type that hands messages to a program; ignored in a queue of another type. § 3.3.10.111.2

How to check on the node
The type of an active queue is printed by the settings command — as the type line at the very start of the queue section:
pmta show settings bounces.example.com/vmta1 | head -5
pmta show queues | head -20
If type shows the previous type while the configuration has changed, messages almost certainly remain in the queue and a service restart is needed. The Hub does not show queue types: all of its queues are smtp.
◇

What else to read

3 articles

◇Node metrics in a standard formatThe node exposes counters, gauges and summaries in a widely accepted format: traffic, connections, errors, queue depth and delays.◇How a message gets into the engineSix described submission methods: extended SMTP, four language bindings and a directory the node watches on disk.◇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.

In the Hub
Cost of a mistake
dangerous: effects outlast a rollback
Scenarios
Connect a sending platform · Collect telemetry