Rate limiting

A misbehaving client, or a compromised account, can open many sessions and issue commands far faster than any person would. Stalwart limits both: how many sessions an account may hold open, and how many commands it may issue in a period of time. No single account can then monopolise the server.

The limits are counted per account, not per connection or per IP address. One set of counters covers IMAP, POP3 and ManageSieve, so a session opened over any of these protocols counts towards the same limits. Both limits are fields of the Imap singleton, found in the WebUI under Settings › Network › IMAP.

Concurrent sessions

An account may hold 16 authenticated sessions at the same time unless maxConcurrentConnections says otherwise. IMAP, POP3 and ManageSieve sessions are counted together.

The limit refuses new sessions rather than closing old ones. A login that would exceed the limit fails with a NO [LIMIT] response (IMAP) or an error response (POP3 and ManageSieve), and the sessions already open are not affected. In a cluster, each server counts the sessions it holds.

The value should leave room for every device of a user. Mail clients commonly open several IMAP connections per device, so a user with a desktop client, a phone and a tablet can reach ten connections or more.

A change to the limit does not reach every account at once. The limit is applied to an account when its session data is loaded into the access token cache. An account that is already cached therefore keeps its previous limit, until its entry is evicted or the InvalidateCaches action runs.

The following object body allows eight sessions per account:

{
  "maxConcurrentConnections": 8
}

Request rate

The number of commands an account may issue within a period is set by rateLimit, given as a count and a period in milliseconds. It is 2000 per minute unless changed.

Each command sent after authentication counts towards the limit, on every session of the account. When the limit is reached, further commands fail with NO [LIMIT] Too many requests, retry in <n> seconds until the period has elapsed. The reply tells a well-behaved client how long to wait. In a cluster, the counters are shared through the in-memory store, and the limit is enforced approximately.

Accounts that hold the unlimitedRequests permission are exempt from the request rate, although the session limit still applies to them.

The following object body allows 600 commands per minute:

{
  "rateLimit": {"count": 600, "period": 60000}
}

Setting either field to null removes that limit. JMAP and other HTTP requests are limited separately, as described in JMAP limits. Connection and request limits discusses how these values interact with server capacity.