mod_sendmail

Send email from a restful HTTP interface, as part of the Mail Service project.

This module is an Apache httpd module that gates an incoming HTTP request to the sendmail application, allowing email to be gated from a restful HTTP endpoint to SMTP. The sendmail application is expected to queue the message for delivery.

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.

The module can be used on its own in "fire and forget" mode to send email in the usual way, or the module can be optionally configured to return a restful URL giving the status of mail delivery, using the processdsn tool, and the mod_processdsn service.

This module requires a functional local mail transfer agent to be present on the same machine, such as Postfix.

Download

Releases of mod_sendmail are hosted by Sourceforge:

mod_sendmail

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

Simple Setup

In order to send email in "fire and forget" mode, mod_sendmail is configured in httpd as a handler as follows. In this example, we use the sendmail binary from Postfix.

<Location /sendmail>

  # protect against open relay
  Order Deny,Allow
  Deny from all
  Allow from 127.0.0.1

  # simple configuration
  SetHandler sendmail
  SendmailName /usr/sbin/sendmail
  SendmailArguments -t -i

</Location>

Setup with AAA

It is possible to protect access to the sendmail endpoint using the standard Apache httpd authentication/authorization mechanisms. It is also possible to extract fields from httpd's authorization CGI variables (such as REMOTE_USER or the AUTHENTICATE_* variables) and use them to set the sender of the email, as in the following example.

<Location /sendmail>

  # basic authentication against an LDAP server
  AuthBasicProvider ldap
  require ldap-group [ldap-group]
  AuthType basic
  AuthName mail-relay
  AuthLDAPBindDN [binddn]
  AuthLDAPBindPassword [password]
  AuthzLDAPAuthoritative on
  AuthLDAPURL ldap://127.0.0.1:389/[basedn]?mail,cn?sub
  AuthLDAPRemoteUserIsDN off

  # sendmail with sender details from LDAP
  SetHandler sendmail
  SendmailName /usr/sbin/sendmail
  SendmailArguments -t -i
  SendmailSenderMail AUTHENTICATE_MAIL
  SendmailSenderName AUTHENTICATE_CN

</Location>

Alternatively, you might secure the sendmail endpoint with a client certificate:

<Location /sendmail>

  # require a client cert
  SSLVerifyClient require
  SSLVerifyDepth 10
  SSLCACertificateFile [certificate-file]

  # sendmail with sender details from LDAP
  SetHandler sendmail
  SendmailName /usr/sbin/sendmail
  SendmailArguments -t -i
  SendmailLocation https://www.example.com/sendmail

</Location>

Setup with Delivery Status Notification

If the processdsn and mod_processdsn tools are configured, it is possible for mod_sendmail to be taught to redirect the end user to a restful URL that will return the result of attempts at email delivery.

This feature allows you to query the delivery status of the email, for both successful delivery, and for delivery failure.

This feature relies on correctly configuring "Delivery Status Notification" and "Variable Envelope Return Path" in the sending MTA. For Postfix, this is configured as follows.

<Location /sendmail>

  # protect against open relay
  Order Deny,Allow
  Deny from all
  Allow from 127.0.0.1

  # configuration with VERP and DSN
  SetHandler sendmail
  SendmailName /usr/sbin/sendmail
  SendmailArguments -t -i -XV -N delay,failure,success -r mail-bounces@example.com
  SendmailLocation http://localhost/sendmail
  SendmailDSNLocation https://www.example.com/dsn

</Location>

In the arguments to the sendmail binary, we request delivery status notification with the "-N" option, Variable Envelope Return Path with the -XV option, and specify the email address to which delivery status notifications should be sent with the -r option. This email address is expected to have the processdsn tool configured to process delivery status notifications sent from the client.

If we specify a value for SendmailDSNLocation, the HTTP caller will be redirected to the URL of the delivery status result, hosted at the URL provided by mod_processdsn.

Sending an Email

To send an email via the service, simply POST the email as an HTTP request, as per the following example:

curl -X POST -d "Hello there" -H "Content-Type: text/plain" \
     -H "To: person@example.com" -H "From: person@example.com" \
     -H "Subject: test" http://localhost/sendmail

Any HTTP client can be used, within reason, including an XmlHttpRequest javascript object, while care should be taken to ensure the endpoint does not become an open relay.

HTTP headers in the request will become SMTP headers in the email, with the exception of the following headers, which will be stripped from the request before sending:

"Cache-Control", "Connection", "Pragma", "Trailer",
"Transfer-Encoding", "Upgrade", "Warning", "Accept",
"Accept-Charset", "Accept-Encoding", "Accept-Language",
"Authorization", "Expect", "Host", "If-Match",
"If-Modified-Since", "If-None-Match", "If-Range",
"If-Unmodified-Since", "Max-Forwards",
"Proxy-Authorization", "Range", "Referer", "TE",
"User-Agent"

Additional headers may be added or manipulated by the Apache httpd server using the mod_headers module.

WADL Interface Definition

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

curl -X OPTIONS http://localhost/sendmail

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

Module Directives

The following directives are understood by this module:

SendmailName /usr/sbin/sendmail: Set to the path and name of the sendmail binary. For example "/usr/sbin/sendmail".
SendmailArguments arguments: Set to the arguments to pass to the sendmail binary. These arguments will depend on the type of MTA in use.
SendmailLocation url: Set to the location of the sendmail service. This URL will be advertised within the WADL description.
SendmailDSNLocation url: Set to the location of the delivery status notification service. On successful acceptance of email, the HTTP client will be redirected to this URL, with the message ID appended.
SendmailSenderMail mail@address: Set to the name of the variable for the sender address. The sender address will be replaced with the contents of this CGI variable, typically REMOTE_USER or AUTHENTICATE_MAIL.
SendmailSenderName sender name: Set to the name of the variable for the sender name. If present, the sender name will be added to the address above, typically AUTHENTICATE_CN.