Demo
Demo

Knowledge base

PMTA knowledge base›Block <domain>›Directive§ 3.3.10.60

type

<domain>restart required

How this queue hands off messages — SMTP, a file, a program, a webhook or not at all
in the configuration this is a linetype smtpinside the block <domain>
A switch between five delivery methods

Decides what the queue does with a message. The default smtp is ordinary sending to the receiver. The other four turn the queue into a handler:

  • file — the message is written to a file; where and in what form is set by file-destination and file-format;
  • pipe — for each recipient the program from the command line is run, and the message is fed to its input;
  • http-delivery — the message goes as a POST request to the address from http-delivery-url as a JSON object;
  • discard — the message is thrown away, and a record goes into accounting; whether it counts as a delivery or a bounce is decided by discard-as-bounce.

The type is set for a recipient domain, not for the node. One node can easily run queues of all five types at once — sending out, parsing bounces with a program and storing an archive in files.

The main trap is changing the type of a non-empty queue. The manual warns in a separate line: if the queue already has messages, changing the type requires a PowerMTA restart. After pmta reload the configuration is new, but the queue works the old way, and this can be noticed only from the settings output.
What the Hub does. It does not write it: all the queues it describes send mail out over ordinary SMTP. The other types are about processing an inbound stream, and the Hub does that on its own side, not on the node.
Recommended values

smtp is for everything that goes out. The other four types have nothing to do with sending a mailing.

pipe versus http-delivery. Both hand the message to someone else’s program, but differently: pipe runs it on this same node for each recipient, http-delivery sends a request over the network. The second is easier to scale, and it copes more honestly with the handler being unavailable — the message stays in the queue and is retried.

discard is not the same as removing the recipient. The message still goes through the queue and into accounting; only the delivery is saved.

The comparison of the pipe and http-delivery types is ours. From the manual here come all five values, the smtp default and the restart requirement when changing the type of a non-empty queue.
Example configuration
# parsing bounces with a program on the same node
<domain bounces.example.com>
    type pipe    command "/opt/bounce/parse --envid \"$envid\" \"$user\""
</domain>

# the same parsing, but over the network — the handler can live anywhere
<domain feedback.example.com>
    type http-delivery    http-delivery-url https://hub.example.com/api/v1/feedback
</domain>
The type line comes first in the block for a reason: the queue’s other lines make sense only for their own type and are silently ignored under another.
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▶

Changing the type without emptying the queue

§ 3.3.10.60

What it costsA configuration reload is not enough — the manual requires a service restart. The queue keeps working the old way, while the configuration looks applied.
How to spot itpmta show settings prints the previous type.
How to do it rightWait for the queue to empty, or restart the service.

Setting discard to avoid sending to bad addresses

our experience

What it costsMessages are still queued, go through the queue and into accounting. Only the connection to the receiver is saved; the work of preparing the messages is wasted.
How to spot itThe volume in accounting does not drop, although delivery is turned off.
How to do it rightFilter addresses at submission — with suppression lists — rather than throwing messages away at the exit.

Setting pipe without specifying a program

§ 3.3.10.111.1

What it costsThe command line is mandatory for a queue of this type. Without it the queue does not know what to run, and messages stall.
How to spot itA pipe queue grows, with zero deliveries.
How to do it rightSet command next to the type — in the same block.
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
type { smtp | pipe | file | discard | http-delivery }
Values
one of five words: smtp, pipe, file, discard or http-delivery
Default
smtp § 3.3.10.60
Applying
a service restart is required
Queue
also affects what is already in the queue
Where to write it
<domain>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The value merges across <domain> blocks from general to specific: the best-matching block wins, not the last one in the file. It is picked up by pmta reload only for an empty queue: if the queue has messages, the manual requires a service restart. A <domain> block can be nested in <virtual-mta> — then the type applies only in that stream.
⇄

Related directives

1 relation

Applies to

Five ways for a queue to hand off a messageThe mechanism as a whole: what each of the five types does and which lines go with it. § 3.3.10.60

How to check on the node
The effective type is printed by the queue settings command — as the type line at the start of the queue section:
pmta show settings bounces.example.com/vmta1 | grep -E '^type'
pmta show queues | grep -i bounces.example.com
A mismatch between the configuration and this output means the type change did not take effect: the queue had messages. The Hub does not set queue types.
◇

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.◇Two inbound report processors and what to do with themBounces by message and complaints are parsed by two identically structured blocks; each has its own address list and its own pair of decisions about the message’s fate.◇Five ways for a queue to hand off a messageA queue does not have to use SMTP: it can write to a file, run a program, call over HTTP or discard.

In the Hub
Cost of a mistake
dangerous: effects outlast a rollback
Scenarios
Collect telemetry
Neighboring settings of the block <domain>:connect-timeoutauth-usernamecommandallow-cancel-during-transferassume-delivery-upon-data-termination-timeoutAll 135 directives of the block →