mod_processdsn

Expose the recorded delivery status of notifications processed by processdsn via a restful HTTP interface, as part of the Mail Service project.

This module is an Apache httpd module that exposes notifications stored in a SQL database using the mod_dbd module and the APR DBD SQL database abstraction layer.

The module responds to the Accept header, and formats the results accordingly.

text/html: Return results as HTML pages, suitable for viewing in a web browser.
text/plain: Results in plain text, suitable for scripting.
text/xml
application/xml: Results as an XML document for an XML parser.
application/json: Results as a JSON document for javascript.

The module is designed to remove the need for machines needing to send email having to have an MTA installed on that machine. The module allows relay protection to be provided using the standard Apache httpd authentication mechanisms, including password based authentication and digital certificates.

Download

Releases of mod_processdsn are hosted by Sourceforge:

mod_processdsn

Releases are available as source tarballs for gzip and bzip2, as well as an SRPM for Redhat/Fedora/CentOS systems.

Setup

To set up the module, configure mod_dbd appropriately to expose the SQL database in use, and configure the "processdsn" handler.

Standard Apache authentication and authorization mechanisms can be used to protect the information, in this example we protect it with a digital certificate.

DBDParams /var/spool/dsn.sqlite
DBDriver sqlite3
ProcessDSNEnable on
<Location /mailpump/dsn>
  SetHandler processdsn
  ProcessDSNLocation https://www.example.com/dsn

  SSLVerifyClient require
  SSLVerifyDepth 10
  SSLCACertificateFile [certificate-file]
</Location>

The DBDParams and DBDriver directives should match those used by the --driver and --params options to processdsn.

Security

In order to remain protected from SQL injection attacks, ensure you use a SQL driver that supports prepared statements. This means that the TDS driver should be avoided.

URL Format

To return the list of recipients detected, pass the message ID as follows:

http://localhost/dsn/<message-id>/

For each recipient, the original headers can be returned as follows, as well as a list of message-ids corresponding to each delivery status notification received:

http://localhost/dsn/<message-id>/<email@address>/

For each explicit delivery status notification, the status can be queried as follows:

http://localhost/dsn/<message-id>/<email@address>/<message-id>/

At this point the headers and result of the notification is returned.

WADL Interface Definition

The current WADL interface definition can be retrieved using the OPTIONS HTTP method, as follows:

curl -X OPTIONS http://localhost/dsn

Use the SendmailLocation directive to define the public base URL for the interface.

Module Directives

The following directives are understood by this module:

ProcessDSNEnable on: Enable the processdsn module and register the prepared statements.
ProcessDSNSummaryHeader X-Message-Action: Set the name of the summary header.
ProcessDSNLocation url: Set the location of the service for the WADL description.