Demo
Demo

Knowledge base

PMTA knowledge base›Block <transmissions-api>›Directive§ 3.3.20.5

max-message-size

<transmissions-api>

The largest request size accepted by the Transmissions API
in the configuration this is a linemax-message-size 100Minside the block <transmissions-api>
The same name 1:<source><transmissions-api>— some of them are other settings, some are the same one
A limit per request, not per message

The default is 100M. The line limits the payload size of a request to the Transmissions API.

The syntax is strict: a number and a mandatory size multiplier — B, K, M or G. The engine will not accept a number without a multiplier. Nor a value above 2G.

The manual specifically warns: messages larger than 100 MB may cause slow acceptance and slow delivery due to increased processing time. That is, the default sits exactly at the boundary beyond which the vendor itself advises not to go.

Do not confuse it with max-message-size of the source block: that one limits a message arriving over SMTP, this one a request arriving over HTTP.

The main trap is that the limit is per request, not per message. A request to the API carries more than the message body: it also holds recipients, substitution values and encoded attachments. The payload ends up noticeably larger than the message itself, and you can hit the limit with a message that would pass freely over SMTP.

The other half: 100M is not a recommendation but a boundary beyond which the manual promises slow acceptance and slow delivery. Raise it with that in mind.

What the Hub does. It does not write it: there is no Transmissions API block in the configuration — submission goes over regular SMTP.

The Hub sets the per-message limit with another line: max-message-size with the value 30M in the address-based submission sources — from the machine itself and from the allowed addresses.

Recommended values

What to set. Count from the request size, not the message size:

Value When
100M (default) suits almost always: beyond this boundary the vendor promises a slowdown
less it is known which messages are submitted, and the limit is set with a margin over their size
more attachments are large, and slower acceptance and delivery are accepted deliberately

The multiplier is mandatory, and the engine will reject a value above 2G.

The 100M default, the mandatory multiplier, the 2G ceiling and the warning about slowdown beyond 100 MB come from the manual, § 3.3.20.5. The breakdown of cases is ours.
Example configuration
# a limit on the request payload, not on the message itself
<transmissions-api>
    max-message-size 100M</transmissions-api>
The multiplier is mandatory: the engine will not accept 100 without a letter. A request carries more than a message — recipients, substitutions and encoded attachments.
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▶

Writing a number without a multiplier

§ 3.3.20.5

What it costsThe engine rejects the value: the multiplier is mandatory. The configuration is not applied at all, and the node stays on the previous one.
How to spot itThe configuration check reports an error in this line.
How to do it rightWrite the number with a size letter — 100M, not 100.

Raising the limit without noticing the warning

§ 3.3.20.5

What it costsBeyond the 100 MB boundary the manual promises slow acceptance and slow delivery due to increased processing time. A raised limit speeds nothing up — it only allows what will be slow.
How to spot itLarge messages are accepted, but acceptance and delivery slow down noticeably.
How to do it rightRaise the limit deliberately and watch processing time, not just the fact of acceptance.
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
max-message-size { N{b|k|m|g} }
Values
a number with a mandatory multiplier B, K, M or G; no more than 2G
Default
100M § 3.3.20.5
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<transmissions-api>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The directive lives in <transmissions-api> and applies to the entry as a whole: there is one block per node, and it has no inheritance. The limit for messages arriving over SMTP is set separately — with the same-named line in the source block.
⇄

Related directives

1 relation

Same name in other blocks

max-message-size<source>The same-named line of the source block limits a message arriving over SMTP; this one a request arriving over HTTP. § 3.3.20.5

How to check on the node
The limit is visible in the configuration; it is worth checking together with the SMTP limit:
grep -n -A3 '^<transmissions-api>' /etc/pmta/config
grep -n 'max-message-size' /etc/pmta/config /etc/pmta/virtualhost.txt
The absence of the block means the entry is not configured at all and the limit affects nothing. Different values for the two same-named lines are normal: they are about different entries.
◇

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
Managed at
Configurations → Delivery limits
Cost of a mistake
reversible: harms only while it is set
Scenarios
Connect a sending platform
Neighboring settings of the block <transmissions-api>:api-keylog-datalog-requestslog-tlsAll 5 directives of the block →