"Fossies" - the Fresh Open Source Software Archive 
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
1
2 mod_sendmail - Send email from a restful HTTP interface.
3 ============
4
5 http://mailservice.sourceforge.net/
6
7 This module is an Apache httpd module that gates an incoming HTTP request
8 to the sendmail application, allowing email to be gated from a restful
9 HTTP endpoint to SMTP. The sendmail application is expected to queue the
10 message for delivery.
11
12 The module is designed to remove the need for machines needing to send
13 email having to have an MTA installed on that machine. The module allows
14 relay protection to be provided using the standard Apache httpd
15 authentication mechanisms, including password based authentication and
16 digital certificates.
17
18 The module can be used on its own in "fire and forget" mode to send email
19 in the usual way, or the module can be optionally configured to return
20 a restful URL giving the status of mail delivery, using the processdsn
21 tool, and the mod_processdsn service.
22
23 This module requires a functional local mail transfer agent to be present
24 on the same machine, such as Postfix.
25
26
27 Simple Setup
28 ------------
29
30 In order to send email in "fire and forget" mode, mod_sendmail is configured
31 in httpd as a handler as follows. In this example, we use the sendmail
32 binary from Postfix.
33
34 <Location /sendmail>
35
36 # protect against open relay
37 Order Deny,Allow
38 Deny from all
39 Allow from 127.0.0.1
40
41 # simple configuration
42 SetHandler sendmail
43 SendmailName /usr/sbin/sendmail
44 SendmailArguments -t -i
45
46 </Location>
47
48
49 Setup with AAA
50 --------------
51
52 It is possible to protect access to the sendmail endpoint using the standard
53 Apache httpd authentication/authorization mechanisms. It is also possible
54 to extract fields from httpd's authorization CGI variables (such as
55 REMOTE_USER or the AUTHENTICATE_* variables) and use them to set the sender
56 of the email, as in the following example.
57
58 <Location /sendmail>
59
60 # basic authentication against an LDAP server
61 AuthBasicProvider ldap
62 require ldap-group [ldap-group]
63 AuthType basic
64 AuthName mail-relay
65 AuthLDAPBindDN [binddn]
66 AuthLDAPBindPassword [password]
67 AuthzLDAPAuthoritative on
68 AuthLDAPURL ldap://127.0.0.1:389/[basedn]?mail,cn?sub
69 AuthLDAPRemoteUserIsDN off
70
71 # sendmail with sender details from LDAP
72 SetHandler sendmail
73 SendmailName /usr/sbin/sendmail
74 SendmailArguments -t -i
75 SendmailSenderMail AUTHENTICATE_MAIL
76 SendmailSenderName AUTHENTICATE_CN
77
78 </Location>
79
80 Alternatively, you might secure the sendmail endpoint with a client
81 certificate:
82
83 </Location /sendmail>
84
85 # require a client cert
86 SSLVerifyClient require
87 SSLVerifyDepth 10
88 SSLCACertificateFile [certificate-file]
89
90 # sendmail with sender details from LDAP
91 SetHandler sendmail
92 SendmailName /usr/sbin/sendmail
93 SendmailArguments -t -i
94 SendmailLocation https://www.example.com/sendmail
95
96 </Location>
97
98
99 Setup with Delivery Status Notification
100 ---------------------------------------
101
102 If the processdsn and mod_processdsn tools are configured, it is possible
103 for mod_sendmail to be taught to redirect the end user to a restful URL
104 that will return the result of attempts at email delivery.
105
106 This feature allows you to query the delivery status of the email, for both
107 successful delivery, and for delivery failure.
108
109 This feature relies on correctly configuring "Delivery Status Notification"
110 and "Variable Envelope Return Path" in the sending MTA. For Postfix, this
111 is configured as follows.
112
113 <Location /sendmail>
114
115 # protect against open relay
116 Order Deny,Allow
117 Deny from all
118 Allow from 127.0.0.1
119
120 # configuration with VERP and DSN
121 SetHandler sendmail
122 SendmailName /usr/sbin/sendmail
123 SendmailArguments -t -i -XV -N delay,failure,success -r mail-bounces@example.com
124 SendmailLocation http://localhost/sendmail
125 SendmailDSNLocation https://www.example.com/dsn
126
127 </Location>
128
129 In the arguments to the sendmail binary, we request delivery status
130 notification with the "-N" option, Variable Envelope Return Path with the
131 -XV option, and specify the email address to which delivery status
132 notifications should be sent with the -r option. This email address
133 is expected to have the processdsn tool configured to process delivery
134 status notifications sent from the client.
135
136 If we specify a value for SendmailDSNLocation, the HTTP caller will be
137 redirected to the URL of the delivery status result, hosted at the URL
138 provided by mod_processdsn. On httpd v2.4 and higher, SendmailDSNLocation
139 is evaluated as an expression using the httpd expression parser.
140
141
142 Sending an Email
143 ----------------
144
145 To send an email via the service, simply POST the email as an HTTP request,
146 as per the following example:
147
148 curl -X POST -d "Hello there" -H "Content-Type: text/plain" \
149 -H "To: person@example.com" -H "From: person@example.com" \
150 -H "Subject: test" http://localhost/sendmail
151
152 Any HTTP client can be used, within reason, including an XmlHttpRequest
153 javascript object (AJAX), while care should be taken to ensure the endpoint
154 does not become an open relay.
155
156 HTTP headers in the request will become SMTP headers in the email, with
157 the exception of the following headers, which will be stripped from the
158 request before sending:
159
160 "Cache-Control", "Connection", "Pragma", "Trailer",
161 "Transfer-Encoding", "Upgrade", "Warning", "Accept",
162 "Accept-Charset", "Accept-Encoding", "Accept-Language",
163 "Authorization", "Expect", "Host", "If-Match",
164 "If-Modified-Since", "If-None-Match", "If-Range",
165 "If-Unmodified-Since", "Max-Forwards",
166 "Proxy-Authorization", "Range", "Referer", "TE",
167 "User-Agent"
168
169 Additional headers may be added or manipulated by the Apache httpd server
170 using the mod_headers module.
171
172
173 Securing the Endpoint
174 ---------------------
175
176 The key security risk that should be mitigated is to ensure that the endpoint
177 cannot become an open relay.
178
179 If any To or CC address is allowed, the endpoint MUST be secured and limited
180 to a particular audience.
181
182 When an XmlHttpRequest / AJAX request is being handled, ensure that the
183 incoming Content-Type is overridden and forced to text/plain to ensure that
184 malware cannot be injected towards an email address:
185
186 <Location /contactus/sendmail>
187
188 SetHandler sendmail
189 SendmailName /usr/sbin/sendmail
190 SendmailArguments -t -i
191 SendmailLocation http://localhost/sendmail
192
193 # Force content type, set To, unset CC
194 RequestHeader set Content-Type text/plain
195 RequestHeader set To someone@example.com
196 RequestHeader unset CC
197
198 </Location>
199
200
201 WADL Interface Definition
202 -------------------------
203
204 The current WADL interface definition can be retrieved using the OPTIONS
205 HTTP method, as follows:
206
207 curl -X OPTIONS http://localhost/sendmail
208
209 Use the SendmailLocation directive to define the public base URL for the
210 interface.
211
212
213 Module Directives
214 -----------------
215
216 The following directives are understood by this module:
217
218 SendmailName: Set to the path and name of the sendmail binary. For example
219 "/usr/sbin/sendmail".
220
221 SendmailArguments: Set to the arguments to pass to the sendmail binary. These
222 arguments will depend on the type of MTA in use. Each argument
223 can be an httpd v2.4 expression.
224
225 SendmailLocation: Set to the location of the sendmail service. This URL
226 will be advertised within the WADL description.
227
228 SendmailDSNLocation: Set to the location of the delivery status notification
229 service. On successful acceptance of email, the HTTP
230 client will be redirected to this URL, with the
231 message ID appended. Each argument can be an httpd v2.4
232 expression.
233
234 SendmailSenderMail: Set to the name of the variable for the sender address.
235 The sender address will be replaced with the contents
236 of this CGI variable, typically REMOTE_USER or
237 AUTHENTICATE_MAIL.
238
239 SendmailSenderName: Set to the name of the variable for the sender name.
240 If present, the sender name will be added to the address
241 above, typically AUTHENTICATE_CN.
242
243