Demo
Demo

Knowledge base

PMTA knowledge base›Block <domain>›Directive§ 3.3.10.92

connection-idle-timeout

<domain>set by the Hub

How long to keep an idle connection open waiting for messages
in the configuration this is a lineconnection-idle-timeout 5minside the block <domain>
How long to keep a connection open without messages

A connection with nothing to send is closed after this interval. Zero means “close as soon as the queue is empty.”

Why keep an empty connection. A TLS handshake costs more than the message itself, and if in half a minute the next message to the same recipient arrives in the queue, reusing the open connection is noticeably cheaper than opening a new one. On a steady stream this saves both time and the connections the provider counts.

The main trap. An open connection occupies a slot both on your side and at the recipient. A large value with an uneven stream means part of the allowed max-smtp-out connections sit idle, while a queue to another recipient waits for a free slot under the node’s ceiling.
What the Hub does. It writes it from the node preset: “Careful” — one minute, “Balanced” — five minutes, “Aggressive” — ten, the engine’s ceiling. Five minutes is enough to survive the pause between batches, and too little to occupy a slot for long.

For addresses under warm-up the line is not written: they have a single connection, and the connection closes as soon as there is nothing to send.

Recommended values
Mode Per address (vMTA) In the provider rule When this is your case
Warm-up, cold address 1m — An address younger than 4–6 weeks or back from a pause
Careful 1m — Strict receivers, questionable reputation, the first weeks after warm-up
Balanced default 5m — Normal operation of an established fleet
Aggressive 10m — Warmed-up addresses, friendly receivers, urgent volumes
PowerMTA default 0 — If the directive is not written at all

The ceiling is set by the engine: ten minutes. The manual will not accept more, and that is reasonable — a connection that has been idle for ten minutes is quite likely to be closed by the receiver itself.

The point is to survive the pause between batches. If messages arrive unevenly, a closed connection has to be reopened, and receivers watch frequent connections more closely than volume. Five minutes cover the usual gap between batches of one mailing.

The default is 0 — the connection closes as soon as there is nothing to send. For a steady stream that is fine; for an uneven one it is wasteful.

The order of magnitude is our recommendation. From the manual here come the 0 default, the 10m ceiling and the purpose: to reduce the number of connections needed and avoid hitting a limit on connection frequency.
Example configuration
# we keep the connection between batches, but no longer than needed
<domain hotmail.com>
    max-smtp-out 15
    connection-idle-timeout 5m</domain>
Five minutes survive the pause between batches of one mailing. Setting ten — the engine’s ceiling — is worth it only where the stream is very uneven.
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▶

Setting more than ten minutes

§ 3.3.10.92

What it costsThe engine’s ceiling is 10m, and the manual names it directly. A larger value will either not be accepted or be cut down, and a calculation built on it will be wrong.
How to spot itThe effective value in the settings output does not match the one written in the configuration.
How to do it rightDo not exceed 10m. If the pause between batches is longer, the connection will have to be reopened anyway, and it is better to account for that in the connection rate.

Keeping connections longer than the stream lasts

our experience

What it costsAn open connection occupies a slot both on your side and at the receiver. With an uneven stream, part of the allowed max-smtp-out will be taken up by idle connections, and there will not be enough of them for messages.
How to spot itThere are as many connections as allowed, but few messages go out.
How to do it rightCut the holding time down to the real pause between batches instead of setting the ceiling “just in case.”
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
connection-idle-timeout <time-interval>
Values
a time interval, no more than 10m; the default 0 means close immediately
Default
0 § 3.3.10.92
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<domain>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The value merges across <domain> blocks from general to specific: the best-matching block wins, not the last one in the file. It is picked up by pmta reload, no restart needed; already open connections live out their time with the old value.
⇄

Related directives

3 relations

Works together with

max-msg-per-connection<domain>The second way to end a connection — by the number of messages rather than by idle time. inferencesmtp-out-rampup-interval<domain>The flip side: holding removes the need to reopen a connection, while the pause slows down opening new ones. § 3.3.10.92

Affects

max-connect-rate<domain>What holding is needed for: reopening connections costs more than keeping an open one. § 3.3.10.92

How to check on the node
The sign that the value works is connections hanging with an empty queue. The effective value is printed by the settings command:
pmta show settings hotmail.com/vmta1 | grep -i idle
pmta show queues --connected=yes --maxitems=20
The second command shows queues with open connections. A queue without messages but with connections is exactly the holding; if there are none, the value is either zero or too small for your stream.
◇

What else to read

3 articles

◇Four value types the whole config is written inBoolean, domain pattern, regular expression and time interval — defined once in § 3.2 and then used by all directives.◇How the policy for a receiver is assembledSettings are assembled from the most general pattern to the most precise; the order of blocks in the file means nothing.◇Backoff mode — the queue's second personalityA queue that a receiver has started refusing switches to a parallel set of limits, retries and routes — ten directives that act only in this mode.

In the Hub
Managed at
Configurations → Delivery limits
Value
The Hub picks it itself — pace, warm-up stage, metrics
Cost of a mistake
reversible: harms only while it is set
Scenarios
Tune the pace for a provider
Neighboring settings of the block <domain>:max-msg-ratemax-smtp-outmax-connect-ratebackoff-max-smtp-outbackoff-max-msg-rateAll 135 directives of the block →