Demo
Demo

Knowledge base

PMTA knowledge base›Block Global›Directive§ 3.3.1.1

total-max-transmissions-api

Global

Ceiling of simultaneous Transmissions API connections
in the configuration this is a linetotal-max-transmissions-api 50inside the block Global
A ceiling on submission over HTTP, not SMTP

How many simultaneous incoming Transmissions API connections the node is willing to serve. This is the second way of submitting messages — not over SMTP but over HTTP: the submitting system sends a message as a request rather than a mail session.

One of three node-level ceilings. Next to it are total-max-smtp-in for incoming mail connections and total-max-smtp-out for outgoing ones. All three limit the PowerMTA instance as a whole, not an individual address or receiver.

The engine sets no upper bound. The manual warns about this separately: any number can be written, but it will run into the capabilities of the machine and the operating system. Too generous a value is not rejected when parsing the configuration — it shows up later, when there really are many connections.

The directive appeared in version six. PowerMTA 5 does not have it, just as it does not have the Transmissions API in its current form.

The main trap. The line limits submission over HTTP and does nothing for SMTP. On a node where everything is submitted in a mail session it takes part in nothing — however much you raise it, the number of submitting connections will hit total-max-smtp-in. It is easy to confuse: the names are similar, both are submission ceilings, both are node-level.
What the Hub does. It does not write it — the vendor fifty stays.

The whole fleet submits messages over SMTP: both the Hub’s warm-up and the submitting platforms open a mail session and hand the message over in it. The Transmissions API is not used by any platform here, so there is nothing to limit. The line will be needed if a platform appears that submits over HTTP.

Recommended values

Do not touch it while submission goes over SMTP. Fifty connections for an interface nobody uses are neither a cost nor a risk.

Raise it based on the number of submitters, not at random. Count the same way as for mail submission: how many parallel requests the platform holds, plus a margin for retries. The manual reminds that the limit is bounded by the machine anyway — each connection takes a descriptor and memory.

Check it together with the mail ceiling. If submission goes both ways, connections add up: a generous number here and a generous one in total-max-smtp-in together run into the same descriptor limit.

The calculation order is our recommendation. From the manual come the default of 50, the warning about the absence of an upper bound and the fact that the limit is set by the machine’s capabilities.
Example configuration
# node-level ceiling — outside any blocks
total-max-transmissions-api 100total-max-smtp-in 100
Both lines are written at the top level of the configuration, without a block. The first counts submission over HTTP, the second — over SMTP; the only thing they share is the machine’s supply of descriptors.
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▶

Raising this ceiling when hitting the mail submission limit

§ 3.3.1.1

What it costsThe line counts only Transmissions API connections. On a node where submission goes over SMTP it affects nothing, and the real limit stays in total-max-smtp-in — where nobody touched it.
How to spot itThe submitting system gets connection refusals, although the ceiling in the configuration has been raised.
How to do it rightSee which interface the submission goes through, and edit that interface’s ceiling. The names are similar, the interfaces are different.

Writing a large number, relying on the engine's check

§ 3.3.1.1

What it costsThe engine does not check the upper bound — a configuration with any number will parse without remarks. Everything will run into the machine’s descriptors and memory, and this will show up under load, not on configuration reload.
How to spot itUnder load connections stop being accepted before the set ceiling; the system log shows descriptor refusals.
How to do it rightCalculate from the machine’s capabilities and check the process descriptor limit. The manual warns about this for all three node-level ceilings.

Looking for the directive on a node with PowerMTA 5

§ 3.3.1.1

What it costsVersion five does not have it. A line carried over from a version-six configuration will be unrecognized — and that is not a typo but a version difference.
How to spot itA configuration that worked on version six is not accepted on version five, and the directive name is not found in its manual.
How to do it rightCheck the node’s version before carrying a configuration over. Verify parsing with the configuration check command, rather than assuming the file is portable between versions.
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
total-max-transmissions-api <number>
Values
a positive integer; the engine does not check the upper bound — the machine sets it
Default
50 § 3.3.1.1
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
Global
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
Not inherited and not overridden: this is a setting of the instance as a whole. It does not appear in blocks and cannot be overridden for an individual address or receiver. It is picked up by pmta reload; connections already open are not dropped when the ceiling is lowered.
⇄

Related directives

3 relations

Works together with

total-max-smtp-inGlobalThe same node-level ceiling for the second submission method — mail. § 3.3.1

Applies to

The Transmissions API listenerLimits connections to the listener described in this block. § 3.3.1.1Submission over HTTPS on its own listener, modeled on SparkPostThe submission method this ceiling belongs to. § 3.3.1.1

How to check on the node
The effective value is printed together with the node’s other settings:
grep -n 'total-max-transmissions-api' /etc/pmta/config
pmta show status
The line may be absent from the configuration entirely — then the vendor fifty applies. The status summary will show how many connections are open now; if the Transmissions API is not used, there will be zero.
◇

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
safe: a wrong value breaks nothing
Scenarios
Connect a sending platform
Neighboring settings of the block Global:always-allow-relayingsmtp-listenerrelay-addresspickuprelay-debugAll 108 directives of the block →