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.
Releases of mod_sendmail are hosted by Sourceforge:
Releases are available as source tarballs for gzip and bzip2, as well as an SRPM for Redhat/Fedora/CentOS systems.
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 firstname.lastname@example.org 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: email@example.com" -H "From: firstname.lastname@example.org" \ -H "Subject: test" http://localhost/sendmail
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.
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.