Demo
Demo

Knowledge base

PMTA knowledge base›Mechanism§ 1.3

How a message gets into the engine

submission interfaces
Six doors, and five of them require code on the submitting side

The manual lists six ways to submit a message: extended SMTP, four language bindings (C/C++, .NET, Perl, Java) and a submission directory that the node watches on disk.

It lists them — and does not describe them. The bindings get a chapter of their own, the submission directory lives among the advanced features. At this level the shape of the list matters, not the details.

And the shape is this: everything except SMTP requires something on the submitting side. A binding is a library that has to be installed and called from code; a submission directory is an agreement to put files where the node looks. SMTP requires nothing: every platform has a mail client.

Hence the choice for platforms. Every mailing system the Hub connects comes in through one of these doors, and in the vast majority of cases it is SMTP — simply because it can do it without modification.

The main trap is choosing a binding for speed. The manual says plainly that bindings are not faster than an ordinary connection, except for merging with several recipients per message. Everything else they offer — personalization and control of an individual message — is also available over SMTP with control headers. So a new dependency in the submitting system buys what is already there.
What the Hub does. It uses only SMTP — both itself and through platforms. The warm-up sender opens a mail session to the submission port, logs in with the common login and names the sending address with the X-Virtual-MTA header.

This is deliberate: every platform can do SMTP, while a binding would require changes in every connected platform. Control headers cover what a binding is taken for — above all, selecting the sending address. The job header X-Job, on the contrary, the Hub turns off in login-based submission sources (process-x-job false): neither warm-up nor a platform sets a job tag.

We do not use the submission directory either. It would be handy where messages are dropped off by a third-party system with no network path to the node, but we have no such setup.

Recommended values

What to submit with and why:

Method What it requires from the submitter When to use
SMTP nothing — any platform can do it our choice, and almost always the right one
binding install a library and write code only for merging with many recipients
submission directory put files where the node looks when there is no network path to the node but the disk is shared

Submission decisions are the same for all doors. The sending address, the job, the encoding are chosen by the submitting side, whatever method it submits with (submission-model). The form of expression changes, not the set of decisions.

The submission directory is the only method without a network. That is its real advantage, not a convenience.

The selection table and the “our choice” verdict are ours. From the manual come the list of six methods itself and the fact that the details are moved to other chapters.
Example configuration
# submission over SMTP: the same decision a binding would make
X-Virtual-MTA: mta-news-1X-Job: campaign-4417
The highlighted line selects the sending address for the message — the same thing a binding does with a call. No library is needed for it.
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▶

Choosing bindings for speed

§ 1.3

What it costsThe manual says plainly: bindings are no faster than an ordinary connection, except for merging with several recipients per message. A new dependency in the submitting system buys what is also available over SMTP with control headers.
How to spot itSwitching to a binding did not change the speed but added a library to the build.
How to do it rightStay on SMTP. Go to a binding only for merging, and only if it is really needed.

Expecting reliability from the submission directory

§ 1.3

What it costsNobody confirms a file placed in the directory: the submitting side does not learn whether the node accepted it. SMTP has a server reply for that, a binding has an exception.
How to spot itSome messages did not go out, and the submitting system does not know it.
How to do it rightUse the submission directory only where there is no network path to the node at all, and build delivery checking separately.

Believing the submission method changes the set of decisions

§ 7

What it costsIt does not. The sending address, the job, the encoding are chosen by the submitting side with any method — only the form differs: a call, a header or a file field.
How to spot itMoving from one door to another comes with a search for “where do I select the sending address here”.
How to do it rightRead the set of decisions once — it is shared — and look only for the notation of the chosen method.
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.
Inheritance
The list has no inheritance — it is an inventory of doors. What is inherited are the settings of the submission block that decides what the submitting side is allowed: whether to obey the address selection header, whether to apply merging, whether to require authentication. The source merge rules there are the usual ones: a narrow block overrides a wide one.
⇄

Related entries

2 relations

Applies to

Accept, route, deliverWhere all six doors lead: the message’s path inside the node. § 1.3

Often used with

What the node tells about itself and through which channelsWhere to see which door messages actually come through. inference

Referenced from

pickupGlobalOne of the submission methods alongside SMTP and HTTP. § 1.3The line ending requirementA related mechanism: they work together. inferenceLatency on receptionMeasures the submission path by which messages arrive at the node. inferenceWhat the submitting system assembles before sendingThe same submission method among the others: bindings are one of the doors into the node. § 7Submitting a message by writing a file into a directoryOne of the submission methods alongside SMTP and HTTP — only without a network. § 11.20

How to check on the node
Which doors messages actually come through is visible in accounting:
grep -o ',smtp,\|,api,' /var/log/pmta/acct-*.csv | sort | uniq -c
pmta show status
The first counts records by submission method: if everything in the fleet goes over SMTP, no other values will appear there. The second shows open incoming connections — they show who is submitting right now.
◇

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.◇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
safe: a wrong value breaks nothing
Scenarios
Connect a sending platform