Mail Queue Management

When Postfix cannot immediately deliver a message — because the recipient server is down, DNS resolution failed, or the destination mailbox is over quota — the message is held in the Postfix mail queue for retry. Admin → Queue gives you a live view of the queue and the ability to take action on individual messages.

How Opterius Mail Accesses the Queue#

Opterius Mail reads the Postfix queue by running the mailq command and parses its output. Queue actions (retry, delete, flush) are executed via postsuper and postfix commands. These commands require elevated privileges.

The installer creates a targeted sudoers entry so that the web application user (www-data) can run only the specific commands needed:

# /etc/sudoers.d/opterius-mail
www-data ALL=(ALL) NOPASSWD: /usr/sbin/postsuper
www-data ALL=(ALL) NOPASSWD: /usr/sbin/postfix flush
www-data ALL=(ALL) NOPASSWD: /usr/bin/mailq

If this entry is missing, the queue page will show an error. You can recreate it manually by adding the above lines to a file in /etc/sudoers.d/.

Reading the Queue Table#

The queue table displays:

Click any row to expand it and see the full Postfix status message, delivery attempts, and next retry schedule.

Queue Depth Chart#

Above the table, a chart shows queue depth over the last 24 hours (sampled every 5 minutes). A steadily growing queue indicates a systemic delivery problem and should be investigated promptly. A queue that rises and falls naturally (peaking during business hours) is normal.

Actions#

Retry a Single Message#

Select a message using its checkbox and click Retry Selected (or click the retry icon on the row). This runs:

sudo postsuper -r {queue-id}

Postfix immediately attempts redelivery rather than waiting for the next scheduled retry interval.

Delete a Single Message#

Select a message and click Delete Selected. This runs:

sudo postsuper -d {queue-id}

The message is permanently removed from the queue. A bounce notification is not automatically sent to the sender — the message simply disappears. Use this for spam, loops, or messages that will never be deliverable.

Retry All Messages#

Click Retry All (Flush Queue). This runs:

sudo postfix flush

Postfix attempts immediate redelivery for every message in the queue. Use this after resolving a delivery issue (e.g., after a DNS misconfiguration is fixed) to avoid waiting for the standard retry schedule.

Caution: Flushing a large queue all at once can cause a burst of outbound connections. If many messages are queued for a destination that has been blacklisting your server, a mass flush may worsen the situation. Review the queue contents before flushing.

Delete All Deferred Messages#

For cases where the queue is full of messages that will never be delivered (e.g., during a spam incident):

# From the command line — not available as a single button in the UI
sudo postsuper -d ALL deferred

This removes all messages from the deferred queue. Use with extreme caution — legitimate undelivered messages will be lost.

Common Reasons for Stuck Messages#

Postfix Retry Schedule#

By default, Postfix retries deferred messages:

• After 5 minutes (first retry)
• After 10 minutes
• After 20 minutes
• Doubling intervals up to maximal_backoff_time (default: 4000 seconds ≈ 67 minutes)
• After maximal_queue_lifetime (default: 5 days), the message bounces and is removed

These values can be adjusted in /etc/postfix/main.cf.