PowerMTA Messages Stuck in Queue — Diagnosis, Retry, and Queue Management

Identifying Stuck Messages

# Messages in queue for more than 2 hours
pmta show queue --age-min=2h

# Messages in queue for more than 24 hours (critically stuck)
pmta show queue --age-min=24h

# By domain
pmta show queue gmail.com
pmta show queue outlook.com

# Check the last deferral reason for stuck messages
grep "gmail.com" /var/log/pmta/accounting.csv | \
  awk -F, '$1=="t" {print $3, substr($10,1,60)}' | \
  sort -k1 -r | head -20   # Most recent deferrals first

# accounting log format 'f' records = messages that expired (never delivered)
awk -F, 'NR>1 && $1=="f" {print $2, $6, $10}' /var/log/pmta/accounting.csv | \
  head -20

Common Causes of Stuck Messages

Forcing Retry Operations

# Retry all deferred messages immediately
pmta retry queue --all
# WARNING: Only use when underlying issue is confirmed resolved

# Retry specific domain
pmta retry queue gmail.com

# Retry by job ID
pmta retry queue --job-id=campaign-2026-01-15

# Retry messages deferred more than 6 hours
pmta retry queue --age-min=6h

# Resume a paused domain
pmta resume queue gmail.com

# After retry, monitor accounting log:
tail -f /var/log/pmta/accounting.csv | awk -F, '{print $1, $6, substr($10,1,40)}'
# Should see 'd' (delivered) records appearing for previously stuck messages

Deleting Stuck Messages

# Delete all messages queued for a specific domain
pmta delete queue --match=rcpt-domain:gmail.com

# Delete by job/campaign ID
pmta delete queue --job-id=campaign-2026-01-15

# Delete messages older than 3 days (cleanup)
pmta delete queue --age-min=3d

# Delete messages matching specific recipient pattern
pmta delete queue --match=rcpt:user@example.com

# Before deleting: consider whether to bounce or silently delete
# Silent delete: sender receives no notification
# Bounce: sends DSN to your bounce-address (informs sending application)
# For campaign messages: silent delete + log is acceptable
# For transactional messages: bounce is preferred so application can retry

Expired Messages and expire-after Configuration

# Messages that exceed expire-after become 'f' (failed) records
# Default expire-after: 5 days (too long for most use cases)

# Recommended expire-after values by message type:
# Transactional (2FA, receipts): 6h - 12h
# Marketing campaigns: 1d - 2d
# Newsletter: 2d - 3d
# General default: 2d

# Configure globally and override per domain:

    expire-after 2d    # Global default


# Shorter expiry for transactional traffic

    expire-after 6h   # 2FA codes are useless after 6 hours


# Check your current expire-after setting
grep -E "expire-after" /etc/pmta/config /etc/pmta/*.conf 2>/dev/null

Prevention: queue depth monitoring Monitoring

# Alert script: send alert if any ISP queue exceeds threshold
#!/bin/bash
declare -A THRESHOLDS=([gmail.com]=20000 [outlook.com]=15000 [yahoo.com]=10000)

for DOMAIN in "${!THRESHOLDS[@]}"; do
    DEPTH=$(pmta show queue $DOMAIN 2>/dev/null | awk '{sum+=$3} END {print sum+0}')
    THRESHOLD=${THRESHOLDS[$DOMAIN]}
    if [ "$DEPTH" -gt "$THRESHOLD" ]; then
        echo "Queue alert: $DOMAIN has $DEPTH messages queued (threshold: $THRESHOLD)" | \
        mail -s "PowerMTA Queue Alert: $DOMAIN" ops@yourdomain.com
    fi
done
# Cron: */15 * * * * /usr/local/bin/check_queue.sh

Frequently Asked Questions