PowerMTA Queue Depth Monitoring and Alerting — Commands, API, and Thresholds

Queue Depth: What It Measures and Why It Matters

PowerMTA's queue contains messages that have been accepted for delivery but have not yet been delivered or bounced. Messages enter the queue at injection and leave when they are either delivered (250 response), bounced (5xx permanent failure), or expired (exceed expire-after time). Messages that receive 4xx deferral responses remain in the queue and are retried at the retry-after interval.

Under normal conditions, queue depth reflects the volume difference between injection rate and delivery rate — for a healthy system sending 1 million messages/hour, you'd expect a queue of perhaps 50,000-100,000 messages at any moment (representing the messages in-flight and awaiting their next retry window). A sudden increase in queue depth without a corresponding increase in injection rate signals a delivery problem.

Queue Monitoring Commands

# Basic queue summary
pmta show queue
# Output: domain | vmta | queued | deferred | age

# Detailed queue by domain
pmta show queue gmail.com
pmta show queue outlook.com

# Full queue listing
pmta show queue --all

# Queue by virtual-mta
pmta show vmta gmail-ip-1
pmta show vmta gmail-ip-2

# Messages stuck over 1 hour (potential delivery problem)
pmta show queue --age-min=1h

# Total queue depth (all domains)
pmta show status | grep queue
# Output: queue depth: 45,231 messages

# Per-domain breakdown
pmta show queue | sort -k3 -rn | head -20    # Sort by queue depth

HTTP Management API for Queue Monitoring

# Enable HTTP management API in /etc/pmta/config
http-mgmt-port 8080
http-mgmt-allow 127.0.0.1/32    # Restrict to localhost

# API endpoints for monitoring:
# GET http://localhost:8080/queue.csv    — queue summary in CSV
# GET http://localhost:8080/status.json  — overall status in JSON
# GET http://localhost:8080/domain.csv  — per-domain statistics

# Python monitoring example:
import requests, json

def get_queue_depth():
    r = requests.get("http://localhost:8080/status.json", timeout=5)
    data = r.json()
    return data["queue_depth"]

def get_domain_queue(domain):
    r = requests.get(f"http://localhost:8080/domain.csv?domain={domain}", timeout=5)
    # Parse CSV response
    return r.text

# Alert if Gmail queue exceeds 50,000
gmail_queue = get_domain_queue("gmail.com")
if int(gmail_queue.split(",")[2]) > 50000:
    send_alert("Gmail queue depth critical")

Production Queue Monitoring and Alerting

# Shell script for queue depth monitoring (run via cron every 15 minutes)
#!/bin/bash
QUEUE=$(pmta show status | grep "queue depth" | awk '{print $3}' | tr -d ',')
THRESHOLD_WARN=50000
THRESHOLD_CRIT=200000

if [ "$QUEUE" -gt "$THRESHOLD_CRIT" ]; then
    echo "CRITICAL: PowerMTA queue depth $QUEUE" | \
    mail -s "PowerMTA CRITICAL: Queue $QUEUE messages" ops@yourdomain.com
elif [ "$QUEUE" -gt "$THRESHOLD_WARN" ]; then
    echo "WARNING: PowerMTA queue depth $QUEUE" | \
    mail -s "PowerMTA WARNING: Queue $QUEUE messages" ops@yourdomain.com
fi

# Per-ISP queue monitoring (more actionable)
for DOMAIN in gmail.com outlook.com yahoo.com; do
    DEPTH=$(pmta show queue $DOMAIN | awk '{sum+=$3} END {print sum}')
    if [ "$DEPTH" -gt "20000" ]; then
        echo "WARNING: $DOMAIN queue depth: $DEPTH" | \
        mail -s "PowerMTA: $DOMAIN queue alert" ops@yourdomain.com
    fi
done

# Cron: */15 * * * * /usr/local/bin/check_pmta_queue.sh

Diagnosing Queue Accumulation

# When queue depth is growing, identify which domain is accumulating:
pmta show queue --all | sort -k3 -rn | head -10

# Then check the deferral reason for that domain:
grep "gmail.com" /var/log/pmta/accounting-YYYYMMDD.csv | \
  awk -F, '$1=="t" {print $10}' | sort | uniq -c | sort -rn | head -5
# Shows the top deferral diagnostic messages for Gmail

# Check when deferrals started:
grep "gmail.com" /var/log/pmta/accounting.csv | \
  awk -F, '$1=="t" {print substr($2,1,13)}' | sort | uniq -c
# Shows deferral count by hour — when did the spike start?

# Identify which source IP is most affected:
grep "gmail.com" /var/log/pmta/accounting.csv | \
  awk -F, '$1=="t" {count[$15]++} END {for(ip in count) print count[ip], ip}' | \
  sort -rn | head -10

Queue Management Operations

# Retry all deferred messages immediately (use with caution)
pmta retry queue --all
# Warning: this re-queues all deferred messages for immediate retry
# Only use when you've fixed the underlying issue

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

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

# Pause delivery to a domain (while investigating)
pmta pause queue gmail.com

# Resume after investigation
pmta resume queue gmail.com

# Move messages between queues
pmta move queue --from=gmail.com --to=gmail.com --vmta=new-pool

Production Alert Thresholds

Frequently Asked Questions