mod_sendmail - Send email from a restful HTTP interface.
============

http://mailservice.sourceforge.net/

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.


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. On httpd v2.4 and higher, SendmailDSNLocation
is evaluated as an expression using the httpd expression parser.


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 (AJAX), 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.


Securing the Endpoint
---------------------

The key security risk that should be mitigated is to ensure that the endpoint
cannot become an open relay.

If any To or CC address is allowed, the endpoint MUST be secured and limited
to a particular audience.

When an XmlHttpRequest / AJAX request is being handled, ensure that the
incoming Content-Type is overridden and forced to text/plain to ensure that
malware cannot be injected towards an email address:

<Location /contactus/sendmail>

  SetHandler sendmail
  SendmailName /usr/sbin/sendmail
  SendmailArguments -t -i
  SendmailLocation http://localhost/sendmail

  # Force content type, set To, unset CC
  RequestHeader set Content-Type text/plain
  RequestHeader set To someone@example.com
  RequestHeader unset CC

</Location>


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: Set to the path and name of the sendmail binary. For example
              "/usr/sbin/sendmail".

SendmailArguments: Set to the arguments to pass to the sendmail binary. These
                   arguments will depend on the type of MTA in use. Each argument
                   can be an httpd v2.4 expression.

SendmailLocation: Set to the location of the sendmail service. This URL
                  will be advertised within the WADL description.

SendmailDSNLocation: 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. Each argument can be an httpd v2.4
                     expression.

SendmailSenderMail: 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: 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.