PowerMTA pmta Command-Line Tool: Complete 2026 Operator Reference

Why the command-line tool matters

PowerMTA provides a web monitor interface, but the command-line tool is where experienced operators do daily work. The CLI is faster for routine checks, scriptable for automation, available over SSH without needing browser access to the monitoring port, and produces output that pipes cleanly into other tools. An operator who knows the pmta command set well diagnoses incidents faster, automates routine operations, and avoids the friction of clicking through a web interface for tasks the CLI does in one command.

This guide exists because the pmta command set is straightforward but under-documented in a way operators actually find useful. The official documentation lists commands; this reference organizes them by what operators actually do with them and explains the operational context. The structure: status and inspection commands for understanding current state, queue control commands for managing delivery, service control for applying changes, counter commands for statistics management, debug mode for troubleshooting, the wildcard syntax that applies across queue commands, the daily operational command set, scripting patterns for automation, and a quick reference table.

Status and inspection commands

The show commands display PowerMTA's current state without changing anything. They are safe to run anytime and form the foundation of operational awareness.

Command	Displays
pmta show status	Overall service health, uptime, version, summary counters
pmta show queues	Active queues with depth, status, connections, rate
pmta show jobs	Active sending jobs with progress
pmta show settings	Current configuration values in effect
pmta show virtual-mtas	VMTA list with current state
pmta show domains	Per-domain delivery statistics

pmta show status is the first command operators run to confirm PowerMTA is healthy. It shows whether the service is running, how long it has been up, the version, and summary delivery counters. A quick health check before diving into any other investigation.

pmta show queues is the most-used command. It lists every active queue with the destination domain, assigned VMTA, current status (normal, backoff, paused), recipient count (queue depth), active connections, current delivery rate, last attempt time, and the timestamp of the oldest queued message. This is the primary diagnostic command for delivery issues.

pmta show jobs lists active sending jobs. When an application submits a batch of messages, PowerMTA tracks them as a job; this command shows job progress, useful for understanding what is currently being sent.

pmta show settings displays the configuration values currently in effect. Critical after a config change to verify the change took effect, because PowerMTA's config parser occasionally accepts a config without applying it as the operator intended.

Queue control commands

The queue control commands change delivery behavior for specific queues. They are the operator's primary tools during incidents.

Command	Effect
pmta pause queue domain/vmta	Stops delivery to the specified queue
pmta resume queue domain/vmta	Resumes a paused queue
pmta set queue --mode=normal domain/vmta	Exits backoff mode for the queue
pmta delete --queue=domain/*	Removes all messages from matching queues
pmta rotate accounting	Forces accounting log rotation

pmta pause queue stops delivery to a queue while keeping queued messages in place. Use during investigation when you want PowerMTA to stop attempting deliveries to a destination without losing the queued messages. The companion pmta resume queue resumes delivery.

# Pause Gmail delivery during investigation
pmta pause queue gmail.com/marketing-pool

# Investigate the issue...

# Resume when ready
pmta resume queue gmail.com/marketing-pool

pmta set queue --mode=normal exits backoff mode manually. When a queue is in backoff because PowerMTA detected throttling, and the operator has addressed the underlying cause and verified the destination accepts mail again, this command exits backoff so PowerMTA resumes normal retry pace.

# Exit backoff for a specific queue after fixing the cause
pmta set queue --mode=normal yahoo.com/marketing-pool

# Exit backoff for all queues at once
pmta set queue --mode=normal */*

pmta delete --queue removes messages from queues. This is destructive: deleted messages do not deliver. Use for stale messages that exceed retry-max-time anyway, or to abandon mail to a specific destination.

# Delete all messages queued for a specific destination
pmta delete --queue=gmail.com/*

Service control: reload, restart, stop

The service control commands manage PowerMTA itself.

Command	Effect	Disruption
pmta reload	Re-reads config without stopping	None
pmta restart / service pmta restart	Full service restart	Brief interruption
service pmta start	Start the service	N/A (was stopped)
service pmta stop	Stop the service	Full stop
pmta show status	Verify service state	None

pmta reload is the preferred way to apply configuration changes. It re-reads the config file without stopping the service: in-flight deliveries continue, queued messages stay queued, active connections are not dropped. Most configuration changes apply cleanly via reload, including domain block changes, VMTA changes, throttling adjustments, smtp-pattern-list changes, and retry directive changes.

pmta restart fully stops and restarts PowerMTA. This interrupts service briefly and drops active connections. Restart is needed only for specific directive changes that PowerMTA cannot apply via reload; the PowerMTA documentation indicates per directive whether a restart is required. Common restart-requiring changes include certain listener-related directives and some low-level service parameters.

The operational rule: default to pmta reload for configuration changes because it is non-disruptive; use pmta restart only when a specific directive requires it or when reload does not produce the expected effect. After any reload or restart, verify the change took effect with pmta show settings or pmta show queues.

Counter and statistics commands

PowerMTA maintains statistics counters that the show commands display. The counter management command:

pmta reset counters resets the statistics counters to zero. Useful after an incident when the operator wants fresh metrics to measure recovery against, or at the start of a measurement period. The reset does not affect queues, deliveries, or configuration; it only zeros the counters that pmta show status and related commands display.

# Reset counters to measure recovery cleanly
pmta reset counters

# Now subsequent show status reflects only post-reset activity

Counter resets are non-destructive and safe to run anytime. The main use is establishing a clean measurement baseline.

Debug mode and diagnostics

For troubleshooting, PowerMTA can run in debug mode.

pmtad --debug runs the PowerMTA daemon in debug mode, producing verbose output about internal operations. This is used when standard diagnostics have not identified a problem and the operator needs to see PowerMTA's detailed internal behavior. Debug mode produces substantial output and is typically run temporarily during a specific investigation rather than as a normal operating mode.

For most diagnostics, the combination of pmta show queues, accounting log analysis, and the PowerMTA log at /var/log/pmta/log provides enough information. Debug mode is the escalation when those do not suffice.

The PowerMTA log itself is a primary diagnostic source. Inspect it with standard tools:

# Recent PowerMTA log activity
tail -100 /var/log/pmta/log

# Watch the log live during an investigation
tail -f /var/log/pmta/log

# Search for errors related to a specific destination
grep yahoo.com /var/log/pmta/log | tail -50

Wildcard syntax for queue commands

The queue control commands accept a wildcard syntax that lets operators apply commands at different scopes.

Pattern	Scope
domain.com/vmta	One specific queue (one domain, one VMTA)
domain.com/*	All queues for one destination domain
*/vmta	All queues using one VMTA
*/*	All queues

The wildcard syntax applies consistently across pause, resume, set queue, and delete. Examples:

# Pause all queues for one destination
pmta pause queue outlook.com/*

# Pause all queues using one VMTA (take an IP out of rotation)
pmta pause queue */marketing-vmta-2

# Exit backoff for all queues
pmta set queue --mode=normal */*

# Delete all messages for one destination
pmta delete --queue=yahoo.com/*

# Resume everything
pmta resume queue */*

The */vmta pattern is particularly useful for IP management: pausing all queues using a specific VMTA effectively takes that IP out of rotation without touching the configuration, useful when an IP develops a reputation problem and needs to rest while the operator investigates.

Daily operational commands

The commands operators actually run as part of daily operations:

Morning health check. The first commands of the operational day:

# Confirm PowerMTA is healthy
pmta show status

# Check for any stuck or backoff queues
pmta show queues | grep -E "BACKOFF|paused"

# Check overall queue depth
pmta show queues

After a configuration change. The verification sequence:

# Apply the config change
pmta reload

# Verify it took effect
pmta show settings

# Confirm queues are processing normally
pmta show queues

During an incident. The investigation sequence:

# See what is stuck
pmta show queues

# Check the log for errors
tail -100 /var/log/pmta/log

# Pause an affected queue while investigating
pmta pause queue affected-domain.com/*

# After resolving, exit backoff and resume
pmta set queue --mode=normal affected-domain.com/*
pmta resume queue affected-domain.com/*

After incident recovery. Establishing a clean baseline:

# Reset counters to measure recovery
pmta reset counters

# Monitor recovery
watch -n 60 'pmta show queues'

These sequences cover the substantial majority of daily PowerMTA operations. The pmta command set is small enough to memorize and the operational patterns become muscle memory quickly.

Scripting pmta commands for automation

Because pmta commands produce parseable output and accept arguments cleanly, they script well for automation.

Queue depth alerting. A script that checks for excessive queue depth and alerts:

#!/bin/bash
# Alert if any queue exceeds depth threshold
THRESHOLD=5000
pmta show queues | awk -v t=$THRESHOLD '
    NR>1 && $5 > t {
        print "ALERT: queue " $1 " depth " $5
    }
' | while read alert; do
    echo "$alert" | logger -t pmta-monitor
    # send notification via your alerting system
done

Backoff detection. A script that detects queues stuck in backoff:

#!/bin/bash
# Report queues in backoff mode
BACKOFF=$(pmta show queues | grep -c BACKOFF)
if [ "$BACKOFF" -gt 0 ]; then
    echo "WARNING: $BACKOFF queues in backoff mode"
    pmta show queues | grep BACKOFF
fi

Automated counter reset. A cron job that resets counters at the start of each measurement period:

# crontab entry - reset counters at midnight
0 0 * * * /usr/sbin/pmta reset counters

Scheduled queue inspection logging. A cron job that logs queue state for historical trending:

# Log queue state every 5 minutes for trending
*/5 * * * * /usr/sbin/pmta show queues >> /var/log/pmta/queue-history.log

The scripting approach lets operators build monitoring and automation on top of the pmta CLI without needing the web monitor or custom API integration. For substantial deployments, the pmta CLI output frequently feeds into Prometheus exporters or similar monitoring as covered in our queue monitoring guides.

Quick reference table

The complete pmta command reference for daily operations:

Command	Purpose
pmta show status	Service health and summary
pmta show queues	Active queues with depth and status
pmta show jobs	Active sending jobs
pmta show settings	Current configuration values
pmta show virtual-mtas	VMTA list and state
pmta show domains	Per-domain statistics
pmta pause queue PATTERN	Stop delivery to matching queues
pmta resume queue PATTERN	Resume matching queues
pmta set queue --mode=normal PATTERN	Exit backoff mode
pmta delete --queue=PATTERN	Remove messages from queues (destructive)
pmta reload	Apply config changes without restart
pmta restart	Full service restart
service pmta start	Start the service
service pmta stop	Stop the service
pmta reset counters	Reset statistics counters
pmta rotate accounting	Force accounting log rotation
pmtad --debug	Run daemon in debug mode

The pmta command-line tool is the primary interface for PowerMTA daily operations. The show commands provide operational awareness, the queue control commands manage delivery during incidents, the service control commands apply changes (with reload strongly preferred over restart), and the whole set scripts cleanly for automation. An operator fluent in the pmta command set works faster, diagnoses incidents quicker, and automates the routine patterns that would otherwise consume attention. The command set is small enough to learn quickly and the operational patterns become second nature with practice. For PowerMTA operators, time invested in CLI fluency pays back every operational day.