Docker Mailserver Mailbox Quota Exceeded? Diagnose and Fix It

Mail to one Docker Mailserver account is bouncing or deferring with mailbox full, quota exceeded, or an enhanced status such as 5.2.2. The obvious response is to increase the limit. That can restore delivery, but it can also hide a runaway mailbox, a broken retention process, a stale quota calculation, or a mail volume incident.

The safe approach is to identify the affected recipient, preserve the exact delivery response, compare Dovecot’s recorded usage with the configured limit and real storage, then make the smallest justified change.

Mailbox quota, Postfix message-size limits, and free disk space are three different controls. Prove which one failed before changing any of them.

First: capture the exact failure

Start with recent mail logs and the queue rather than the user’s mail client. Use your real Compose service name:

docker compose logs --since 2h mailserver

docker compose exec mailserver postqueue -p

Keep this output private: it can contain recipient addresses, senders, queue IDs, and message metadata. Look for the delivery transport, enhanced status, and text around one affected queue ID. Local Dovecot/LMTP quota rejection is different from a remote recipient telling your outbound Postfix that their mailbox is full.

• Local recipient plus Dovecot/LMTP quota message: continue with this guide.
• Remote MX returns mailbox full: your server cannot repair the recipient’s storage; allow normal queue/bounce handling.
• Message too large: inspect message-size policy, not mailbox quota.
• No space left on device: treat it as host or volume capacity failure before touching per-user quotas.

1. Confirm quotas are enabled

Docker Mailserver exposes Dovecot quota support through ENABLE_QUOTAS. Inspect the resolved Compose configuration and the container’s effective Dovecot settings without publishing environment output:

docker compose config

docker compose exec mailserver doveconf -n | grep -i quota

Review the first command locally because it may interpolate sensitive environment values. The Docker Mailserver documentation defines ENABLE_QUOTAS=1 as enabling Dovecot quotas. If quota commands say the plugin is unavailable, do not force a recalculation: first compare your pinned image version and Compose configuration with the documented quota setup.

2. Read the account’s recorded usage and limit

Dovecot’s supported read-only check is doveadm quota get. Substitute the affected full mailbox address:

ACCOUNT='[email protected]'

docker compose exec mailserver \
  doveadm quota get -u "$ACCOUNT"

The result normally reports a quota root, used storage, limit, and percentage. Interpret it before changing anything:

• Usage is genuinely near or above the limit: archive/delete mail or deliberately raise the account limit.
• Usage looks impossible after a restore or manual file move: the quota count may be stale.
• No limit appears: verify account provisioning and quota configuration rather than assuming the mailbox is unlimited.
• The account is unknown: confirm the exact mailbox identity, aliases, domain, and account provisioner.

An alias may ultimately deliver into another account’s mailbox. Docker Mailserver’s quota-aware account handling exists so aliased delivery can share the real mailbox location and limit; diagnose the resolved mailbox, not merely the address the sender typed.

3. Check real filesystem and inode capacity

A mailbox can be below its personal quota while the Docker volume or host is full. Check both blocks and inodes from the mail container:

docker compose exec mailserver df -h

docker compose exec mailserver df -i

If the mail volume is full, raising a user quota makes the situation worse. Stop nonessential producers, preserve logs, identify safe cleanup candidates, and expand or recover storage according to your backup plan. Do not delete unfamiliar files directly from a Maildir or Dovecot index tree to buy space.

Also compare the Docker volume mount with your intended Compose file. A missing persistent mount can place mail on an unexpected container filesystem; the Docker Mailserver backup and restore runbook explains which mail, state, and configuration data need protection.

4. Find the configured mailbox limit

For Docker Mailserver’s file provisioner, per-account limits are maintained by its setup tooling and represented in the quota configuration. Inspect the command help for the version you actually run:

docker compose exec mailserver setup quota help

The documented setter accepts an account and a size such as 2G or 500M:

# Example only: choose a justified limit for the real account
ACCOUNT='[email protected]'

docker compose exec mailserver \
  setup quota set "$ACCOUNT" 2G

Do not blindly copy 2G. First check current usage, storage headroom, backup capacity, growth rate, and the reason for the increase. Keep the change in your persistent Docker Mailserver configuration and confirm it survives a controlled container recreation.

Docker Mailserver also exposes POSTFIX_MAILBOX_SIZE_LIMIT, expressed in bytes, but that Postfix control is not a substitute for a Dovecot per-user quota. Avoid changing global limits when one account has reached a deliberate personal allowance.

5. Repair a stale quota count only when evidence supports it

Dovecot documents quota recalc for recalculating current usage. It is appropriate when the recorded number is demonstrably wrong—for example, after a supported restore or an out-of-band storage repair—not as a routine way to make a full mailbox accept more mail.

ACCOUNT='[email protected]'

# Preserve the before state
docker compose exec mailserver \
  doveadm quota get -u "$ACCOUNT"

# Recalculate only this account
docker compose exec mailserver \
  doveadm quota recalc -u "$ACCOUNT"

# Compare the result
docker compose exec mailserver \
  doveadm quota get -u "$ACCOUNT"

If recalculation restores a high usage figure, the mailbox is still genuinely full. If it changes the figure substantially, record why the old accounting became stale and verify the underlying mail store before declaring the incident closed.

6. Reduce usage through the mailbox, not with filesystem deletion

For a genuinely full account, the safest first option is usually user-visible cleanup through IMAP: archive required messages, empty Trash/Junk according to policy, and verify that deletions are expunged. This keeps Dovecot’s mailbox indexes and quota accounting involved.

Before a large deletion, confirm the mailbox is covered by a tested backup and that retention or legal requirements allow it. If automated mail has filled the account, fix the producer or retention rule too. Extra quota without source control only delays the next outage.

7. Retry one affected message and prove delivery

After freeing space, correcting a stale count, or raising a justified limit, retry one known queued message if it remains deferred:

docker compose exec mailserver \
  postqueue -i REPLACE_WITH_QUEUE_ID

docker compose logs --since 5m mailserver

Confirm the chosen queue ID reaches a successful local delivery status, appears in the intended mailbox, and no fresh quota warning is emitted. Then check whether the queue count and oldest age decline normally. Do not repeatedly flush every message; the deferred queue guide shows how to group and retry only affected mail.

Common wrong turns

• Setting every account to unlimited: removes a useful containment boundary and lets one mailbox consume the mail volume.
• Deleting Dovecot index or Maildir files by hand: risks inconsistency, data loss, and misleading accounting.
• Running quota recalc repeatedly: recalculation measures usage; it does not create capacity.
• Confusing a remote 5.2.2 with your own mailbox: inspect the relay and recipient before changing local configuration.
• Increasing quota on a full filesystem: turns a per-user issue into a server-wide failure.
• Deleting queued mail first: discards delivery evidence without repairing the mailbox.

A safe recovery checklist

1. Preserve the exact queue ID, delivery transport, recipient, and status text privately.
2. Prove the rejection belongs to a local mailbox rather than a remote recipient.
3. Check ENABLE_QUOTAS and effective Dovecot quota configuration.
4. Read the account’s usage and limit with doveadm quota get.
5. Check mail-volume block and inode capacity.
6. Choose one repair: safe mailbox cleanup, justified limit change, or evidence-backed recalculation.
7. Retry one queue ID and verify successful delivery into the correct mailbox.
8. Confirm the configuration persists and monitor usage growth.

The Docker Mailserver file-provisioner documentation documents setup quota set and persistent account quota configuration. The environment reference distinguishes Dovecot quotas from Postfix’s mailbox-size control. Dovecot’s official doveadm-quota manual defines the read and recalculation commands.

A successful fix is not merely an empty queue. It is a mailbox whose real usage is understood, whose limit matches an intentional storage policy, whose volume has headroom, and whose next test message can be traced from Postfix through LMTP into the account.