Demo
Demo

Knowledge base

PMTA knowledge base›Block Global›Directive§ 3.3.1.8

spool-max-recipients

Global

A ceiling on the number of recipients across all spool directories at once
in the configuration this is a linespool-max-recipients autoinside the block Global
A safety fuse against what the node cannot handle

The default is auto: the engine calculates the ceiling itself, from the machine’s resources.

The line limits the number of recipients across all spool directories at once. The manual names the purpose directly: not to let the node be overloaded with more messages than it can process.

Above the ceiling, submission is refused with a temporary error — that is, the submitting side learns about it right away and can retry later.

What is counted is recipients, not messages: a message to a thousand addresses takes a thousand places.

The main trap is counting messages. A ceiling of a million looks huge until a mailing goes out as messages to many addresses at once. A thousand messages to a thousand recipients each is already a million, and submission will stop halfway.

The second half: the auto default is calculated from the machine’s resources, not from your plans. On a small node it will turn out lower than expected, and you will hit it suddenly — in the middle of a mailing, with temporary refusals at submission.

What the Hub does. It does not write it — auto remains, that is, the ceiling is calculated from the node’s resources.

For warm-up this makes no difference: it submits messages one recipient at a time and in small batches, far from the ceiling. The line would become important on a node where a sending platform submits in large batches.

Recommended values

What to set. The number is calculated from mailing volume, not from disk size:

Value When
auto (default) volumes are small or unknown — the engine will calculate from the machine
an explicit number the largest mailing size is known, and it must fit entirely

An explicit number is worth taking with headroom for retries: messages to problematic receivers stay in the queue for days and occupy places all that time.

The auto default, the calculation from machine resources, the temporary refusal above the ceiling and counting by recipients come from the manual, § 3.3.1.8. The advice about headroom for retries is ours.
Example configuration
# the largest mailing must fit entirely, with headroom for retries
spool-max-recipients 10000000
Recipients are counted, not messages: a mailing of a thousand messages to a thousand addresses each will take a million places.
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▶

Counting the ceiling in messages rather than recipients

our experience

What it costsA mailing of messages to many addresses exhausts the ceiling a thousand times faster than expected. Submission stops with temporary refusals in the middle of sending.
How to spot itSubmission is refused with a temporary error, even though there are few messages in the queue.
How to do it rightRecalculate the ceiling in recipients: a message to a thousand addresses takes a thousand places.

Relying on automatic calculation for a large mailing

§ 3.3.1.8

What it costsThe ceiling is calculated from the machine’s resources, not from your plans. On a small node it will turn out lower than expected, and you will hit it in the middle of a mailing.
How to spot itTemporary refusals at submission start at a certain volume and repeat from mailing to mailing.
How to do it rightSet the number explicitly, calculated from the largest mailing with headroom for retries.
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
spool-max-recipients { N | auto }
Values
an integer number of recipients or auto
Default
auto § 3.3.1.8
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
The directive is written at the root of the configuration file and applies to the whole node at once: the ceiling is shared across all spool directories, and it cannot be divided among them.
⇄

Related directives

2 relations

Depends on

How to turn a sending plan into hardwareThe ceiling is one of the two headroom boundaries; the other is memory. § 1.7.1.2

Works together with

max-memory-usage-percentGlobalA neighboring safety fuse: that one counts memory, this one places in queues. inference

How to check on the node
The ceiling is visible in the configuration, what is occupied in the node’s status:
grep -n 'spool-max-recipients\|max-memory-usage-percent' /etc/pmta/config
pmta show status | head -20
A missing line means auto — the engine calculates the ceiling, and it can be seen only from behavior: temporary refusals at submission with a non-empty queue mean that this is exactly what was hit.
◇

What else to read

3 articles

◇What makes a virtual machine riskyRunning on a virtual machine is possible, but the manual does not recommend it without sufficient hardware and properly tuned hypervisor settings: under load the node may stop responding.◇The activation key is a prerequisite for installation, not a step after itWithout an activation key from SparkPost support the engine neither installs nor runs, and the license tier sets the outbound connection ceiling: on Standard everything above 200 is ignored.◇What the node tells about itself and through which channelsSeven observation surfaces: the web monitor, the console in four formats, the log, accounting, accounting search, metrics and export to external analytics.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Capacity planning · Untangle a stuck queue
Neighboring settings of the block Global:spool-delete-corruptedspoolspool-min-free-spacesmtp-proxy-source-hostdomain-keyAll 108 directives of the block →