How can I monitor PowerMTA queue sizes by domain and set up alerts for stuck emails?
Michael Ko
Co-founder & CEO, Suped
Published 17 Apr 2025
Updated 16 Aug 2025
8 min read
Managing an email marketing platform, especially with a high-volume MTA like PowerMTA, means constantly keeping an eye on your outgoing mail flow. One of the most critical aspects of this is monitoring queue sizes by domain and identifying when emails get stuck. A burgeoning queue can quickly escalate into deliverability issues, poor sender reputation, and ultimately, lost revenue from undelivered campaigns.
Stuck emails typically indicate an underlying problem, whether it's a domain-specific block, a misconfigured DNS record, or even an issue with the recipient's mail server. Proactive monitoring and alert systems are essential to catch these problems before they significantly impact your email deliverability. Without proper oversight, you might only discover issues when your campaigns underperform or when recipients complain about not receiving messages.
My goal is to outline practical steps for setting up robust monitoring and alerting for your PowerMTA queues. This includes leveraging PowerMTA's built-in capabilities, external scripting, and understanding the different types of queue delays.
Accessing PowerMTA queue data
PowerMTA provides several ways to access queue information, but for automated monitoring, the web user interface (web UI) can be configured to export data in a machine-readable format. If you have the web UI enabled, typically on port 8080, you can access domain-specific queue data in JSON or XML format. This programmatic access is the foundation for building effective monitoring scripts.
To retrieve queue sizes by domain, you can adapt your web UI URL. If your PowerMTA web UI is accessible at, for example, `https://yourserverhostname:8080/ui/`, you can modify it to `https://yourserverhostname:8080/domains?format=json`. This endpoint will provide a JSON output containing detailed information about each domain's queue, including the number of messages waiting, active connections, and other relevant metrics. This is a powerful feature for extracting granular data about your email flow. For deeper insights into PowerMTA's capabilities, consult the official PowerMTA user guide.
Once you have the JSON data, you can use a scripting language like Python or Bash with tools like `curl` and `jq` to parse it. The script would iterate through the domain queues, extract the message count for each, and then compare it against predefined thresholds. For instance, you might set a threshold of 100 messages for major email providers like gmail.com or outlook.com.
Python script to fetch PowerMTA queue datapython
import requests
import json
pmta_url = "https://yourserverhostname:8080/domains?format=json"
username = "your_username"
password = "your_password"
def get_queue_data():
try:
response = requests.get(pmta_url, auth=(username, password), verify=False)
response.raise_for_status() # Raise an exception for HTTP errors
return response.json()
except requests.exceptions.RequestException as e:
print(f"Error fetching PowerMTA data: {e}")
return None
if __name__ == "__main__":
data = get_queue_data()
if data:
for domain_entry in data['data']:
domain_name = domain_entry['name']
queue_size = domain_entry['queue_size']
print(f"Domain: {domain_name}, Queue Size: {queue_size}")
Setting up alerts for stuck emails
With the ability to retrieve queue sizes, the next step is to set up alerts. For critical domains (e.g., Gmail, Outlook, Yahoo), you'll want immediate notifications if queues exceed a certain threshold. You can integrate your monitoring script with various alerting mechanisms, such as email, SMS, or even chat platforms like Slack or Microsoft Teams. For general guidance on improving email delivery, consider reviewing resources on email deliverability monitoring.
Beyond external scripting, PowerMTA itself offers internal directives that can help manage queue behavior and provide some level of notification. The notify-of-delay-every directive, for example, allows you to set how often PowerMTA checks whether delay notification messages should be sent for messages with the NOTIFY=DELAY option in the RCPT TO command. While not a direct queue size alert, it can help identify prolonged delivery delays for specific messages. For an overview of deliverability monitoring options, check out our guide.
Example PowerMTA configuration for delay notificationstext
Automated alerting can also benefit from integrating with third-party services for push notifications or more sophisticated incident management. This ensures that critical queue build-ups are not missed, even when you're not actively monitoring. Setting up a dedicated monitoring system can save a lot of headaches later. Remember, a robust system helps catch issues before they impact your sender reputation or lead to your IP addresses being added to a blacklist (or blocklist).
Common reasons for stuck queues
Understanding why emails get stuck in the queue is as important as knowing that they are stuck. PowerMTA's logging and reporting can provide clues. Common reasons include DNS issues, recipient server rejections (e.g., due to a full mailbox or Gmail mailbox full bounces), or temporary greylisting by the receiving MTA. Regularly reviewing PowerMTA's logs, especially the smtp.log, can help diagnose these issues.
For ongoing health, configuring MX-rollup lists in your PowerMTA configuration can aggregate statistics for different mail exchangers under a single domain. This is particularly useful for large providers that use multiple MX records or subdomains for email delivery. By grouping these, you get a consolidated view of deliverability to major ISPs, making it easier to spot issues that might otherwise be scattered across many individual domain entries.
Another powerful tool in preventing stuck queues is diligent blacklist monitoring (or blocklist monitoring). If your IP or domain gets listed, emails will likely pile up in the queue for affected recipient domains. Regularly checking your IP and domain against major blocklists can help you react quickly. Tools and practices for understanding email blacklists are essential for any sender. A sudden increase in queue size, especially for a specific domain, can be an early indicator of a blocklist event or a spam trap hit.
DNS issues: Incorrect or missing MX records for a recipient domain can lead to emails accumulating in the queue. Always verify DNS records if you suspect issues.
Recipient server problems: The recipient's mail server might be temporarily down, overloaded, or rejecting connections due to its own policies or issues.
Sender reputation: If your IP or domain has a poor reputation (e.g., due to high spam complaints or being on a blacklist/blocklist), recipient servers may intentionally defer or reject your mail, causing queues to grow. This is where tools for checking blocklists become invaluable.
Configuration errors: Incorrect PowerMTA configuration, such as misconfigured delivery routes or rate limits, can inadvertently cause email queues.
Network issues: Temporary network connectivity problems between your PowerMTA server and the recipient's mail server can also lead to queues.
Conclusion
Monitoring PowerMTA queue sizes by domain and setting up alerts for stuck emails is a critical component of successful email operations. By leveraging PowerMTA's web UI data, external scripting, and understanding the core reasons for queue build-ups, you can maintain healthy email flow. Proactive monitoring helps you quickly identify and resolve deliverability issues, safeguarding your sender reputation and ensuring your messages reach their intended recipients.
Implementing these monitoring and alerting practices allows you to be informed the moment a problem arises, rather than discovering it hours or days later when campaign performance dips significantly. This proactive approach is key to maintaining high deliverability rates and ensuring your email programs run smoothly. Regularly reviewing your queue data can also reveal trends over time, helping you optimize your sending strategy.
Ultimately, the goal is to prevent revenue loss and maintain customer trust that stems from reliable email delivery. Consistent monitoring is not just about reacting to problems, it's about anticipating them and building a resilient email infrastructure. Understanding how to interpret SMTP response codes also greatly assists in troubleshooting why emails are getting stuck.
Views from the trenches
Best practices
Implement automated scripts to regularly pull queue data from PowerMTA's web UI, parsing it to identify specific domain queue sizes and growth trends.
Set up dynamic thresholds for alerts, adjusting them based on historical data and typical sending volumes for different domains to avoid false positives.
Utilize PowerMTA's internal directives like 'notify-of-delay-every' for additional insight into prolonged delivery delays and integrate with external monitoring tools.
Common pitfalls
Relying solely on manual checks of the PowerMTA web UI, which makes it easy to miss sudden queue build-ups and critical deliverability problems.
Ignoring the root causes of queue increases, such as DNS misconfigurations, recipient server issues, or IP/domain blacklistings (blocklistings).
Failing to set up granular, domain-specific alerts, leading to generic notifications that don't pinpoint the exact source of a deliverability problem.
Expert tips
Consider leveraging external logging and monitoring systems (like ELK stack or Grafana) to centralize PowerMTA logs and queue metrics for advanced visualization and anomaly detection.
Regularly review your PowerMTA configuration, especially 'mx-rollup-list' directives, to ensure domains are correctly grouped for accurate queue reporting and routing.
Automate the remediation process where possible, such as automatically retrying certain deferred emails or routing traffic to alternative IPs if queues for a specific domain spike.
Expert view
Expert from Email Geeks says enabling the PowerMTA web UI and accessing the '/domains?format=json' endpoint is crucial for programmatic monitoring of queue sizes by domain.
2022-01-05 - Email Geeks
Marketer view
Marketer from Email Geeks says once you have the JSON queue data, it's straightforward to parse it with a script and send alerts to your team.
