Demo
Demo

Knowledge base

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

file-format

<domain>

In what form the queue writes messages to files
in the configuration this is a linefile-format newfile-plaininside the block <domain>
Three file types to choose from

It works for a file queue (type). It decides what exactly ends up on disk:

  • newfile-plain — the default. Each message gets its own file containing the whole message with headers. There are no envelope addresses in it — neither sender nor recipient.
  • newfile-pickup — the same plus two service headers, x-sender and x-receiver, which hold the envelope addresses.
  • append-mbox — all messages are appended to one file in the unix mailbox format.

The file appears twice. The node first creates it with a .tmp extension and renames it to .msg only after writing it to the end. Whoever parses these files must skip .tmp — otherwise sooner or later they will read half a message.

The main trap is that the default loses the envelope. newfile-plain writes the message as is, and envelope addresses are not stored in the message: the envelope recipient and the recipient in the To header are different things, and in mailings they diverge constantly. Such an archive can no longer be parsed for “who it went to.” You need newfile-pickup.
What the Hub does. It does not write it: it creates no file queues. If such a queue is ever needed for an archive, newfile-pickup is the one to take — the Hub links a message to a recipient by the envelope, not by the header.
Recommended values

newfile-pickup is almost always better than the default. It differs from it by two header lines but keeps the envelope.

append-mbox — when there are many small messages. A separate file per message at large volumes turns the directory into a file system problem.

Read the shared file properly. The node holds a lock while appending; the vendor advises using pmtagetfile rather than reading the file directly.

The advice to prefer newfile-pickup is ours. From the manual here come all three types, the default, the newfile-pickup service headers, the scheme with temporary and final file extensions and the vendor’s recommendation about accessing the shared file.
Example configuration
# an archive that keeps the envelope
<domain archive.example.com>
    type file
    file-destination /var/spool/archive/$isodate/
    file-format newfile-pickup</domain>
With newfile-pickup, every file will get x-sender and x-receiver headers with the envelope addresses — that is what the archive is parsed by.
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▶

Keeping the default and losing the envelope addresses

our experience

What it costsnewfile-plain writes neither the envelope sender nor the envelope recipient. In mailings the To header does not equal the envelope, and who the message went to can no longer be restored from the archive.
How to spot itThe archive files have no x-sender and x-receiver headers.
How to do it rightSet newfile-pickup — it differs by exactly these two lines.

Parsing the directory without skipping .tmp

§ 3.3.10.110.1

What it costsThe node creates a file with a .tmp extension and renames it to .msg only after finishing writing. A handler that reads everything will sooner or later take an unfinished message.
How to spot itTruncated messages occasionally turn up in processing.
How to do it rightRead only .msg, skip .tmp.
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
file-format <enumeration>
Values
one of three words: newfile-plain, newfile-pickup or append-mbox
Default
newfile-plain § 3.3.10.110.1
Applying
reload, no restart needed
Queue
will not touch what is already queued
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. In a queue of another type the line is ignored — it is present in the settings output and does nothing. It is picked up by pmta reload.
⇄

Related directives

1 relation

Does not work without

Five ways for a queue to hand off a messageThe line works only for a queue that writes to a file; in a queue of another type it is ignored. § 3.3.10.110.1

How to check on the node
The value is printed by the queue settings command; the file type is visible from the directory itself:
pmta show settings archive.example.com/vmta1 | grep -i file-format
ls -la /var/spool/archive/ | head -10
Files with the .tmp extension in the output are messages the node is still writing: they must not be read. The Hub does not create file queues.
◇

What else to read

3 articles

◇How a message gets into the engineSix described submission methods: extended SMTP, four language bindings and a directory the node watches on disk.◇Who is allowed to submit mail and for whom to accept itOut of the box, the node accepts submission only from the machine itself; two different questions — “who can send through us” and “for whose addresses we accept mail” — are answered by different directives.◇Headers the sender uses to control deliverySix control headers let the submitting side choose a stream, tag a message with a job, set signing options and the key, the envelope identifier and the schedule; each is allowed separately and per source.

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