Contents
Why the HTTP interface matters
A PowerMTA deployment cannot be operated well without monitoring, and the HTTP interface is the foundation of that monitoring. It is how an operator sees PowerMTA's state in a browser, and, more importantly, how an automated monitoring system collects PowerMTA's metrics continuously. Configuring the HTTP interface, and securing it properly, is part of setting up any production PowerMTA deployment.
This guide exists to cover the HTTP interface thoroughly, including the security that must accompany it. The structure of this guide: why the HTTP interface matters, what it provides, configuring it in the PowerMTA configuration, the critical matter of securing access to it, integrating PowerMTA into a monitoring system through its machine-readable data, the relationship between the HTTP interface and the pmta command-line tool, what management actions are possible, and the diagnostic workflow when the HTTP interface is not accessible.
What the HTTP interface provides
PowerMTA exposes an HTTP service, and it serves two purposes, two audiences.
A human-readable monitoring console. Accessed with a web browser, the HTTP interface presents a monitoring console showing PowerMTA's current state: the virtual MTAs and their status, the queues and their depths, the per-domain breakdown, the delivery activity, the general health of the deployment. An operator can open this in a browser and see at a glance what PowerMTA is doing.
Machine-readable data. The HTTP interface also exposes the same operational data in a machine-readable form. This is the more important capability for ongoing operations: it means a monitoring system can poll the HTTP interface and collect PowerMTA's metrics programmatically, the queue depths, the delivery rates, the VMTA states, the same way the monitoring system collects any other metric.
| Audience | Uses |
|---|---|
| A person | The browser console for a quick look at PowerMTA's state |
| A monitoring system | The machine-readable data for continuous, automated metric collection |
So the HTTP interface is the foundation of monitoring the deployment: the human console for a quick look, and the machine-readable data for the continuous, trended, alerted monitoring that a production deployment needs. Both capabilities come from the same HTTP service; configuring and securing it makes both available.
Configuring the HTTP interface
The HTTP interface is configured in the PowerMTA configuration file, with directives that enable the interface and set the port it listens on.
The configuration enables the HTTP service and specifies the network port it is available on:
# Enable the HTTP monitoring interface on a port
http-mgmt-port 8080With the HTTP interface enabled on a port, PowerMTA listens on that port for HTTP connections, and the monitoring console and the machine-readable data are available there.
The configuration of the HTTP interface also includes, crucially, the access restrictions covered in the next section. The interface should never be configured to simply listen openly; the enabling of the interface and the restriction of access to it are configured together, as one step, so the interface is never openly reachable even briefly.
The exact directives for the HTTP interface, and the full set of options, are in the PowerMTA documentation, which is the reference for the specifics. The conceptual point is that the HTTP interface is a configured feature, enabled and given a port in the PowerMTA configuration, and like any configuration change, enabling or changing it follows the validate-then-reload workflow, edit the configuration, run the configuration check, and reload once it validates.
Once configured and the configuration reloaded, the HTTP interface is available on its port, ready to serve the console to a browser and the data to a monitoring system, within the access restrictions configured.
Securing access to the interface
Securing the HTTP interface is not optional, it is an essential part of configuring it, and it is done primarily by restricting which hosts can reach the interface.
The reason security matters: the HTTP interface exposes operational information about the mail system, the domains, the volumes, the queues, the VMTAs, and depending on configuration it can permit management actions. That information should not be public, and an interface permitting management actions that is openly reachable is a direct security hole.
An unrestricted, openly-reachable PowerMTA HTTP interface is a serious security problem. Anyone on the internet who finds it can see the deployment's operational state, the domains being sent to, the volumes, the queues, information that should never be public. If the interface permits any management action, an open interface lets a stranger affect the mail system. The HTTP interface must be locked down so that only trusted hosts, the operator's management network, the monitoring system's host, the administrators' access points, can reach it. This is configured as part of enabling the interface, not added later, so the interface is never, even for a moment, openly accessible.
The security measures, applied together:
PowerMTA's access restriction. The PowerMTA configuration for the HTTP interface allows restricting access to specified hosts or IP ranges. The operator configures this so only the trusted sources, the monitoring system, the management network, the administrators, can reach the interface, and nothing else.
A network firewall. In addition to PowerMTA's own restriction, the interface's port should be protected by a firewall that blocks access from anything but the trusted hosts. This gives two layers, PowerMTA's configuration restriction and the firewall, both limiting access, so a gap in one is covered by the other.
Internal-only reachability. Ideally, the HTTP interface is reachable only over the internal network or a secured management channel, not bound to or reachable on any public-facing interface.
These measures together ensure the HTTP interface is available to the operator's own monitoring and administration and to nothing else. Securing the interface is configured in the same step as enabling it, because an interface enabled without the restrictions is openly exposed from the moment it starts, and that exposure, even briefly, is a risk.
Integrating into a monitoring system
The most valuable use of the HTTP interface is integrating PowerMTA into a monitoring system, using the machine-readable data.
A production PowerMTA deployment needs continuous, trended, alerted monitoring, not occasional manual checks. The HTTP interface's machine-readable data is what makes that possible. The integration:
- The monitoring system polls the HTTP interface. The operator's monitoring and metrics platform periodically polls PowerMTA's HTTP interface, reading the machine-readable operational data, the queue depths, the delivery rates, the VMTA states, and the rest.
- The metrics are stored as a time series. The polled values are stored over time, so the trends are preserved and visible.
- Dashboards display the state. The metrics are displayed on dashboards, so an operator can see PowerMTA's health and trends at a glance.
- Alerts fire on problem conditions. The monitoring system's alerting fires when the metrics indicate a problem, a growing queue, a delivery rate drop, a VMTA issue.
The result is PowerMTA's operational state turned into active, automated monitoring. The queue depth becomes a trended, alerted metric. The delivery rate becomes a dashboard line with alerting. The VMTA states are watched continuously.
The HTTP interface's machine-readable data being available is precisely what enables this, the monitoring system reads PowerMTA's metrics the same way it reads any other system's. An operator generally does not need a PowerMTA-specific monitoring product; their existing monitoring platform can poll the HTTP interface. This integration is a core part of operating a PowerMTA deployment properly, and the HTTP interface is its foundation, which is one of the main reasons the HTTP interface is configured and secured as a standard part of deployment setup.
The HTTP interface and the pmta tool
PowerMTA offers two ways to interact with it, the HTTP interface and the pmta command-line tool, and understanding how they differ helps an operator use each well.
| Aspect | pmta command-line tool | HTTP interface |
|---|---|---|
| Accessed | On the server, at the command line | Over the network, browser or monitoring system |
| Best for observation | Hands-on, on-server checks | Networked monitoring, automated collection |
| Best for management | The primary route for management actions | Primarily observation |
The pmta command-line tool is run on the PowerMTA server itself. It provides commands for observing PowerMTA, such as pmta show queues for the queues or pmta show status for the status, and for managing it, such as pmta reload to apply a configuration change or pmta pause queue to pause a queue. The pmta tool is the operator's direct, interactive way of working with PowerMTA when on the server.
The HTTP interface is accessed over the network with a browser or a monitoring system, not at the server's command line.
For observing PowerMTA's state, the two overlap, both show the queues, the VMTAs, the status, but they suit different situations. The pmta tool is convenient when the operator is already on the server doing hands-on work. The HTTP interface is what allows monitoring from elsewhere and, crucially, allows a monitoring system to collect the data programmatically.
For management actions, the pmta command-line tool is the primary, most direct route. An operator applying a configuration change or pausing a queue typically does so with pmta.
So the practical division: the pmta tool is the hands-on, on-server interface for both observation and management; the HTTP interface is the networked, integrate-with-monitoring interface, primarily for observation. A well-run deployment uses both, the pmta tool for direct operator work on the server, the HTTP interface as the foundation of the automated, networked monitoring.
What management actions are possible
The HTTP interface is primarily an observation interface, but the question of what management actions are possible through it is worth addressing clearly.
PowerMTA's management actions, applying a configuration change with a reload, pausing and resuming queues, and the other operational controls, are most directly and most commonly performed with the pmta command-line tool on the server. That is the standard route for management.
The HTTP interface's central role is observation, presenting the state to a browser and the data to a monitoring system. An operator should think of the HTTP interface primarily as the monitoring window, not as the management console.
This has a security implication that reinforces the earlier section. Because the HTTP interface is primarily for observation, and management is done with pmta on the server, the HTTP interface can and should be locked down tightly to the trusted monitoring and administration sources without that lockdown impeding management, management does not depend on broad HTTP access. The interface being observation-focused and the management being done on the server via pmta means the HTTP interface can be restricted as tightly as possible.
The exact set of actions the HTTP interface itself supports is a matter for the PowerMTA documentation and the specific version, and an operator should consult the documentation for the precise capabilities. But the operational model to adopt is clear: use pmta on the server for management actions, and use the HTTP interface for observation and monitoring integration. Keeping that division means the HTTP interface is locked down as a pure monitoring window, which is the safest posture.
When the HTTP interface is not accessible
When the HTTP interface is not accessible, from a browser or from the monitoring system, the diagnostic workflow:
Step 1: confirm the interface is enabled and PowerMTA is running. Check that the HTTP interface is enabled in the PowerMTA configuration, with its port configured, and that PowerMTA itself is running. The HTTP interface is part of PowerMTA, so if PowerMTA is down, the interface is too.
Step 2: confirm the configuration was reloaded. If the HTTP interface configuration was recently added or changed, confirm PowerMTA was reloaded so the change took effect.
Step 3: confirm PowerMTA is listening on the port. On the server, check that PowerMTA is actually listening on the configured HTTP interface port. If it is not, the interface is not enabled correctly or PowerMTA did not start it.
# Check that PowerMTA is listening on the HTTP interface port
ss -tlnp | grep 8080Step 4: check the access restriction. If PowerMTA is listening but the access is being refused, check PowerMTA's HTTP interface access restriction. The host trying to reach the interface, the browser's host or the monitoring system's host, must be among the permitted sources. An access restriction that is too tight, not including a host that should have access, blocks that host.
Step 5: check the firewall. If PowerMTA is listening and its access restriction permits the host, check the network firewall. The firewall must allow the connection from the accessing host to the interface's port. A firewall rule blocking the port blocks access even when PowerMTA itself would allow it.
Step 6: distinguish a too-tight restriction from a too-open one. When adjusting access, the goal is the precise set of trusted hosts, not opening access broadly. If a host that should have access does not, add that specific host to the permitted set, do not loosen the restriction generally. The interface must stay locked down to the trusted sources.
Step 7: verify after a fix. After adjusting the configuration or the firewall, confirm the configuration was reloaded if PowerMTA's config changed, and verify the interface is now reachable from the intended host and still not reachable from anywhere it should not be.
An operator we worked with had set up their HTTP interface well. They had enabled it, given it a port, and, taking security seriously, locked access down tightly through PowerMTA's restriction and a firewall rule. Their monitoring system polled the interface, and for a while everything worked. Then they migrated their monitoring platform to a new host with a new IP, a routine change. Afterward, their PowerMTA dashboards went blank. The queue trend, the delivery rate, the VMTA states all stopped updating. They worried PowerMTA had a problem, but it was sending mail fine, and the pmta tool on the server showed everything healthy. The cause was the access restriction. They had locked the interface to a set of trusted hosts that included the old monitoring system's IP. When they migrated to a new IP, that new IP was in neither PowerMTA's restriction nor the firewall rule, so the new host's polling was refused, exactly as the lockdown is designed to refuse any unrecognized host. The monitoring system was doing its job; the interface was, correctly, refusing it. The fix was simple: add the new host's IP to both the PowerMTA restriction and the firewall rule. Once it was on the trusted list, the dashboards came back. The lesson concerns maintaining the access restriction. Locking the interface down is correct, but the restriction is a list of specific trusted hosts, and that list must be kept in step with the infrastructure. When a trusted host changes, a monitoring system moving IPs, an admin access point changing, the restriction must be updated to match in both places. A too-tight restriction is the correct state, not a problem, but an out-of-date one that omits a host that legitimately needs access quietly breaks the monitoring, and the fix is to update the trusted list, not loosen it.
The HTTP interface is the foundation of monitoring a PowerMTA deployment, serving both as a browser console and as a source of machine-readable data a monitoring system polls continuously. It is enabled and given a port in the configuration, and it must be secured in the same step, restricted through PowerMTA's access control and a firewall so only trusted hosts reach it, because an open interface leaks operational information and is a security hole. The machine-readable data enables the real prize: integrating PowerMTA into a monitoring system for continuous, trended, alerted visibility. The interface complements the pmta tool, which is the hands-on, on-server route for observation and management, while the HTTP interface is the networked, observation-focused one, and a good deployment uses both. Operators who enable the interface, lock it to the trusted hosts, and wire it into their monitoring get the visibility a production deployment needs; those who leave it open create an exposure, and those who lock it down but let the trusted-host list go stale quietly break their own monitoring.