PowerMTA HTTP API Configuration

Enabling the PowerMTA HTTP Management Interface

PowerMTA includes an HTTP management interface that exposes queue statistics, domain-level data, and operational control endpoints via HTTP. This interface enables monitoring integration with external dashboards, alerting systems, and automation scripts without requiring SSH access to the PowerMTA server.

# /etc/pmta/config — enable HTTP management API
http-mgmt-port 8080
# Restrict access to trusted IPs only
http-mgmt-allow 127.0.0.1/32
http-mgmt-allow 10.0.0.0/8       # Internal monitoring network
# http-mgmt-allow 0.0.0.0/0     # NEVER expose publicly — no auth on this endpoint

# Apply change
pmta reload
# Verify: curl http://localhost:8080/status.json

Available API Endpoints

The most commonly used endpoint for monitoring is /status.json, which provides a snapshot of overall PowerMTA health in JSON format. Parse this endpoint every 60 seconds for dashboard integration.

Monitoring Integration Examples

# Python monitoring script — poll API every minute
import requests, json, time, smtplib
from email.mime.text import MIMEText

def check_pmta():
    try:
        r = requests.get('http://localhost:8080/status.json', timeout=5)
        data = r.json()
        queue = data.get('queue_depth', 0)
        rate = data.get('msgs_per_sec', 0)
        
        if queue > 100000:
            send_alert(f'CRITICAL: PowerMTA queue depth {queue:,}')
        elif queue > 50000:
            send_alert(f'WARNING: PowerMTA queue depth {queue:,}')
            
        return queue, rate
    except Exception as e:
        send_alert(f'ERROR: Cannot reach PowerMTA API: {e}')
        return None, None

# Prometheus metrics integration
def expose_prometheus():
    queue, rate = check_pmta()
    return f"""# HELP pmta_queue_depth Current PowerMTA queue depth
# TYPE pmta_queue_depth gauge
pmta_queue_depth {{server="mail1"}} {queue}
# HELP pmta_msgs_per_sec Messages per second
pmta_msgs_per_sec {{server="mail1"}} {rate}
"""

Domain-Level API Queries

# Query queue depth for specific ISP
curl -s 'http://localhost:8080/queue.csv?domain=gmail.com' | \
  awk -F, '{sum+=$3} END {print "Gmail queue:", sum, "messages"}'

# Get delivery rate by domain (last 60 seconds)
curl -s 'http://localhost:8080/domain.csv' | \
  awk -F, 'NR>1 {print $1, "delivered:", $4, "deferred:", $5}' | \
  head -20

# Per-virtual-MTA statistics
curl -s 'http://localhost:8080/vmta.csv' | \
  awk -F, 'NR>1 {print $1, "msgs/s:", $3}'

HTTP API for Automated Queue Management

# Trigger retry via API POST
curl -s -X POST http://localhost:8080/command \
  -d 'retry queue gmail.com'

# Pause delivery to specific domain
curl -s -X POST http://localhost:8080/command \
  -d 'pause queue outlook.com'

# Resume after investigation
curl -s -X POST http://localhost:8080/command \
  -d 'resume queue outlook.com'

# Get queue age statistics
curl -s -X POST http://localhost:8080/command \
  -d 'show queue --age-min=1h'

Integrating with Grafana and Alertmanager

For production monitoring dashboards, integrate the PowerMTA HTTP API with a time-series database (Prometheus/InfluxDB) and visualization layer (Grafana). A simple exporter script polls the API endpoints every 60 seconds and pushes metrics. Grafana dashboards then visualize queue depth trends, per-ISP delivery rates, and per-IP throughput over time — giving operators the temporal context needed to identify emerging reputation issues before they become delivery incidents.

# systemd service for PowerMTA Prometheus exporter
# /etc/systemd/system/pmta-exporter.service
[Unit]
Description=PowerMTA Prometheus Exporter
After=pmta.service

[Service]
ExecStart=/usr/local/bin/pmta_exporter.py --port=9099 --pmta-api=http://localhost:8080
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

# Access metrics at: http://localhost:9099/metrics
# Add to Prometheus scrape config:
# - job_name: powermta
#   static_configs:
#     - targets: ['localhost:9099']

HTTP API Integration Patterns

The PowerMTA HTTP management API enables monitoring integration without SSH access. Poll /status.json every 60 seconds for dashboard integration. Use /queue.csv filtered by domain for per-ISP queue depth alerts. The /command POST endpoint enables operational actions (retry, pause, resume) from external automation tools. Restrict access to the management port to trusted internal IPs — the API has no built-in authentication.

Accounting Log Analysis for This Configuration

Monitor this configuration area through the PowerMTA accounting log's dsnDiag field. Filter accounting records for the specific ISP domains affected by this configuration and group dsnDiag responses by first 60 characters to identify the dominant error patterns. A deferral rate above 5% at any single ISP warrants investigation; above 15% requires immediate volume reduction and configuration review.

The dlvSourceIp field in the accounting log enables per-IP analysis within this configuration context. Comparing per-IP deferral rates identifies whether a configuration issue affects all IPs in a pool uniformly (configuration problem) or just specific IPs (reputation or IP-specific problem). This distinction determines the correct remediation path.

Calibrating to Your Current Environment

The parameter values documented in this reference are appropriate for established, warmed IPs with HIGH reputation at the target ISP. New or warming IPs, and IPs with MEDIUM or LOW reputation, require more conservative values. Move up incrementally as reputation signals confirm the infrastructure can sustain additional throughput. Review ISP-specific configuration monthly — Postmaster Tools reputation tier changes and SNDS status changes are the primary triggers.

Production Deployment Summary

Implementing this PowerMTA configuration correctly in production requires testing the specific parameter values against your actual IP reputation history, ISP distribution, and sending volume. The values documented here represent proven starting points, not fixed constants — your optimal configuration may differ based on your infrastructure's operational history.

After applying any configuration change, monitor the accounting log for the first 2-4 hours to verify the change produced the expected effect on deferral rates. A configuration change that was expected to reduce deferrals but shows no change (or increased deferrals) indicates either: the change addressed the wrong variable, or there is a confounding factor that needs investigation before continuing.

The Cloud Server for Email infrastructure team manages PowerMTA environments daily, applying the configuration principles documented in this reference series across clients with varied volume levels, ISP distributions, and reputation histories. Contact us at infrastructure@cloudserverforemail.com for a technical assessment of your specific PowerMTA configuration requirements.