Knowledge base

PMTA knowledge base›Mechanism§ 11.20

Submitting a message by writing a file into a directory

pickup directory submission

Submission without a network and without a protocol

A submission method with neither a connection nor a protocol: the message is written as a file into the designated directory, from which the engine picks it up.

The envelope is passed in special headers at the start of the file. First comes x-sender — the sender, on one line. After it x-receiver, one line per recipient. Optionally — x-envid and x-job. The requirement is strict: addresses only, without names and without angle brackets.

There is also x-sender-override: if present, its content overrides the sender from x-sender. It was invented for programs that do not let you set the sender but allow adding an arbitrary header.

No message processing takes place. The manual says it plainly: apart from reading and removing these headers, the engine does nothing with the message — formatting is entirely up to you.

A recipient named only in x-receiver but not in the message headers gets a blind copy — that is how a hidden mailing is done with this method.

The manual advises no more than 5,000 recipients per file.

And a performance caveat: creating the file directly in the directory is possible but less efficient — the engine repeatedly tries to take exclusive possession of it while writing is not finished. It is better to assemble the file elsewhere and move it.

The main trap is that “no processing” means literally none. No format check, no header correction, no filling in of missing ones. The message will leave exactly as you wrote it — with all the markup errors that protocol submission would have caught.

The second half is assembling the file directly in the directory. The engine will start trying to take it without waiting for the write to finish, and will keep trying again and again. It works, but it costs more than moving a finished file.

What the Hub does. It does not use it: it submits messages over SMTP with a login. The pickup directory is not declared in the configuration — so it does not work either.

The method would be useful where the submitting side cannot do SMTP or must not go over the network. For the fleet this is not our case: submission goes from the Hub itself over the network, and a login is needed there anyway.

Example configuration

# the envelope — the first lines of the file, then an ordinary message
x-sender: me@over.here
x-receiver: you@over.therex-receiver: someone.else@some.other.place
x-job: sale-2026-08
From: Myself <me@over.here>
Subject: I love it

Hey, did you know that ...

The second recipient is not named in the message headers — they will get a blind copy. The engine reads and removes the envelope headers and leaves everything else as is.

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▶

Expecting the engine to fix the message format

§ 11.20

What it costsNo processing takes place at all: the message leaves exactly as written. Markup errors that protocol submission would have caught reach the recipient.

How to spot itMessages from the pickup directory display differently for recipients than those submitted over SMTP.

How to do it rightCheck the format on the submitting side: the engine will not do it.

Assembling the file directly in the pickup directory

§ 11.20

What it costsThe engine starts trying to take the file without waiting for the write to finish, and repeats the attempts. It works, but it costs more than moving a finished file.

How to spot itThe pickup directory is processed more slowly than expected, with few files.

How to do it rightAssemble the file elsewhere and move it into the directory finished.

Putting more than 5,000 recipients in a file

§ 11.20

What it costsThe manual advises staying within this limit. A file beyond it takes long to process, and the whole time it is locked — while an error in it costs the whole batch at once.

How to spot itIndividual pickup files take noticeably longer to process than the rest.

How to do it rightSplit the batch into files of a few thousand recipients.

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

3 relations

Same name in other blocks

How a message gets into the engineOne of the submission methods alongside SMTP and HTTP — only without a network. § 11.20

Works together with

Two tags the sender puts on a messageBoth tags have a header form, so file submission can set them too. § 11.20 Mail merge via SMTP extensionsHere merging is set not by protocol commands but by the file format. § 11.19.5.3

How to check on the node

Whether the directory is set up is visible in the configuration; whether it works — by the bad-messages directory:

grep -n 'pickup' /etc/pmta/config
ls -l /opt/pickup/new /opt/pickup/badfiles 2>/dev/null

Files accumulated in the bad-messages directory mean a format error on the submitting side. Files lingering in the pickup directory itself mean the engine cannot take exclusive possession of them.

◇

What else to read

3 articles

◇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.◇The load balancer header at the entranceThe node reads the PROXY header at the start of an incoming connection and treats the address from it as the source; this works for both kinds of entry point.

In the Hub

Cost of a mistake: reversible: harms only while it is set
Scenarios: Node security · Connect a sending platform