2021/01/13 by Maarten Oelering.
HTTP based APIs and webhooks in PowerMTA 5.0
The standard protocol for transferring email is SMTP and the MIME standard is used to encode emails before transfer. As the leading email delivery engine, PowerMTA's implementation of SMTP is extremely robust and performant. It also supports the latest SMTP extensions for internationalisation, authentication and encryption.
But SMTP and MIME do not communicate well with modern applications with other languages: HTTP and JSON. This can make integrating a MTA in an infrastructure based on web standards challenging. Luckily PowerMTA has supported a list of HTTP based APIs and webhooks since version 5.0.
Available PowerMTA APIs and webhooks
In total, there are four APIs available in release 5.0r6:
- Transmissions API for submitting mail for delivery
- Configuration API for updating configuration files
- Command API for executing commands
- Monitoring API for getting status reports
There are two webhooks which can be used to push data to a web application:
- Delivery webhook for receiving incoming emails
- Accounting webhook for receiving transaction data
In this post, we will describe the Transmissions API and the Accounting webhook in more detail. With these two you can turn PowerMTA into your private SMTP delivery service, similar to services like Sparkpost Cloud and Sendgrid.
PowerMTA Transmissions API
The Transmissions API can be used to submit emails for delivery via HTTP. Previously, developers had to use an SMTP client library or the PowerMTA client libraries to submit emails. With this API, submitting an email is as simple as calling any other web API: create a JSON object and post it to a URL.
The API is similar to the Transmissions API in Sparkpost Cloud but it does not support all the features provided by Sparkpost Cloud. An important difference is that PowerMTA expects a pre-built email which is already encoded for transmission. This means that the caller needs to apply transfer encoding of the content and create a proper MIME encoded email.
PowerMTA Accounting webhook
Probably the most interesting HTTP API is the Accounting webhook. This webhook allows you to push event data such as bounce and complaint data to web applications. Before the built-in webhook became available, Postmastery used their webhook add-on which is set up on dozens of PowerMTA systems.
The webhook works in a similar way to the event webhooks provided by SMTP delivery service providers. Event data such as receptions, deferrals, deliveries, bounces and complaints are posted to a URL of choice. Each post contains a batch of events encoded as newline delimited JSON or CSV and will be retried in case of errors.
Configuration of HTTP APIs
Setting up the HTTP APIs is explained in the User's Guide and is quite easy to do. What can be a bit tricky is HTTPS. We can help you set up a validating certificate from Let's Encrypt for endpoints and CA certificates for webhooks.