"Fossies" - the Fresh Open Source Software Archive
The requested HTML page contains a <FORM> tag that is unusable on "Fossies" in "automatic" (rendered) mode so that page is shown as HTML source code (style: standard
) with prefixed line numbers.
Alternatively you can here view
the uninterpreted source code file.
4 FormMail Version 3.14m1
5 Copyright 2001-2003 London Perl Mongers, All rights reserved
9 This script is free software; you are free to redistribute it
10 and/or modify it under the same terms as Perl itself.
14 The most up to date version of this script is available from the nms
15 script archive at <http://nms-cgi.sourceforge.net/>
19 formmail is a script which allows you to receive the results of an
20 HTML form submission via an email message.
24 In this distribution, you will find the following files:
26 FormMail.pl - The main Perl script
27 README - This file. Instructions on how to install and use formmail
28 EXAMPLES - Some worked examples of ways to set up formmail
29 ChangeLog - The change history of these files
30 MANIFEST - List of files
31 lib/CGI/NMS/Charset.pm - A module required by FormMail.pl
32 lib/CGI/NMS/Validator.pm - A module required by FormMail.pl
33 lib/CGI/NMS/Script.pm - A module required by FormMail.pl
34 lib/CGI/NMS/Script/FormMail.pm - A module required by FormMail.pl
35 lib/CGI/NMS/Mailer.pm - A module required by FormMail.pl
36 lib/CGI/NMS/Mailer/ByScheme.pm - A module required by FormMail.pl
37 lib/CGI/NMS/Mailer/Sendmail.pm - A module required by FormMail.pl
38 lib/CGI/NMS/Mailer/SMTP.pm - A module required by FormMail.pl
42 There are a number of variables that you can change in FormMail.pl which
43 alter the way that the program works.
45 $DEBUGGING - This should be set to 1 whilst you are installing
46 and testing the script. Once the script is live you
47 should change it to 0. When set to 1, errors will
48 be output to the browser. This is a security risk and
49 should not be used when the script is live.
51 $emulate_matts_code - When this variable is set to a true value (e.g. 1)
52 formmail will work in exactly the same way as its
53 counterpart at Matt's Script Archive. If it is set
54 to a false value (e.g. 0) then more advanced features
55 are switched on. We do not recommend changing this
56 variable to 1, as the resulting drop in security
57 may leave your formmail open to use as a SPAM relay.
59 $secure - When this variable is set to a true value (e.g. 1)
60 many additional security features are turned on. We
61 do not recommend changing this variable to 0, as the
62 resulting drop in security may leave your formmail
63 open to use as a SPAM relay.
65 $allow_empty_ref - Some web proxies and office firewalls may strip
66 certain headers from the HTTP request that is sent
67 by a browser. Among these is the HTTP_REFERER that
68 the program uses as an additional check of the
69 requests validity - this will cause the program to
70 fail with a 'bad referer' message even though the
71 configuration seems fine. In these cases setting
72 this variable to 1 will stop the program from
73 complaining about requests where no referer header
74 was sent while leaving the rest of the security
75 features intact.
77 $max_recipients - The maximum number of e-mail addresses that any
78 single form should be allowed to send copies of the
79 e-mail to. If none of your forms send e-mail to more
80 than one recipient, then we recommend that you
81 improve the security of FormMail by reducing this
82 value to 1. Setting this variable to 0 removes all
83 limits on the number of recipients of each e-mail.
85 $mailprog - The system command that the script should invoke to
86 send an outgoing email. This should be the full path
87 to a program that will read a message from STDIN and
88 determine the list of message recipients from the
89 message headers. Any switches that the program
90 requires should be provided here.
92 A $mailprog setting that works for many UNIX-like
93 hosts is:
95 $mailprog = '/usr/lib/sendmail -oi -t';
97 Some other UNIX-like hosts need:
99 $mailprog = '/usr/sbin/sendmail -oi -t';
101 If your web server lacks a sendmail binary, you can
102 use an SMTP relay instead, by setting $mailprog like
105 $mailprog = 'SMTP:mailhost.your.domain';
107 You will need to replace mailhost.your.domain with
108 the name or IP address of an SMTP server configured
109 to relay mail for the web server.
111 Your system administrator or hosting provider should
112 be able to tell you either the path to sendmail on the
113 web server or the name of a host that will act as an
114 SMTP relay for the web server.
116 $postmaster - The envelope sender address to use for all emails
117 sent by the script. This address will recieve bounce
118 messages if any of the emails cannot be delivered. If
119 in doubt, put your own email address here.
121 @referers - A list of referring hosts. This should be a list of
122 the names or IP addresses of all the systems that
123 will host HTML forms that refer to this formmail
124 script. Only these hosts will be allowed to use the
125 formmail script. This can be used to prevent others
126 from linking to FormMail.pl from their own HTML forms.
128 If you wish to turn off referer checking so that forms
129 that use this FormMail.pl can reside on any web server
130 then make this array empty, like this:
132 @referers = ();
134 @allow_mail_to - A list of the email addresses that formmail can send
135 email to. The elements of this list can be either
136 simple email addresses (like 'firstname.lastname@example.org') or
137 domain names (like 'your.domain'). If it's a domain
138 name then *any* address at the domain will be allowed.
140 Example: to allow mail to be sent to 'email@example.com'
141 or any address at the host 'mail.your.domain', you
142 would set:
144 @allow_mail_to = qw(firstname.lastname@example.org mail.your.domain);
146 @recipients - A list of Perl regular expression patterns that
147 determine who the script will allow mail to be sent
148 to in addition to those set in @allow_mail_to. This is
149 present only for compatibility with the original
150 formmail script. We strongly advise against having
151 anything in @recipients as it's easy to make a mistake
152 with the regular expression syntax and turn your
153 formmail into an open SPAM relay.
155 There is an implicit $ at the end of the regular
156 expression, but you need to include the ^ if you want
157 it anchored at the start. Note also that since '.' is
158 a regular expression metacharacter, you'll need to
159 escape it before using it in domain names.
161 If that last paragraph makes no sense to you then
162 please don't put anything in @recipients, stick to
163 using the less error prone @allow_mail_to.
165 %recipient_alias - A hash for predefining a list of recipients in the
166 script, and then choosing between them using the
167 recipient form field, while keeping all the email
168 addresses out of the HTML so that they don't get
169 collected by address harvesters and sent junk email.
171 For example, suppose you have three forms on your
172 site, and you want each to submit to a different email
173 address and you want to keep the addresses hidden.
174 You might set up %recipient_alias like this:
176 %recipient_alias = (
177 '1' => 'email@example.com',
178 '2' => 'firstname.lastname@example.org',
179 '3' => 'email@example.com',
182 In the HTML form that should submit to the recipient
183 'firstname.lastname@example.org', you would then set the recipient
186 <input type="hidden" name="recipient" value="2" />
188 The recipients in %recipient_alias are automatically added
189 to the allowed recipients list, so there's no need to list
190 them all in @allow_mail_to as well.
192 @valid_ENV - A list of all the environment variables that you want
193 to be able to include in the email. See 'env_report' below.
195 $locale - This determines the language that is used in the date - by
196 default this is blank and the language will probably be
197 english. The following a list of some possible values,
198 however it should be stressed that not all of these will
199 be supported on all systems and also this is not a complete
202 Catalan ca_ES
203 Croatian hr_HR
204 Czech cs_CZ
205 Danish da_DK
206 Dutc nl_NL
207 Estonian et_EE
208 Finnish fi_FI
209 French fr_FR
210 Galician gl_ES
211 German de_DE
212 Greek el_GR
213 Hebrew he_IL
214 Hungarian hu_HU
215 Icelandic is_IS
216 Italian it_IT
217 Japanese ja_JP
218 Korean ko_KR
219 Lithuanian lt_LT
220 Norwegian no_NO
221 Polish pl_PL
222 Portuguese pt_PT
223 Romanian ro_RO
224 Russian ru_RU
225 Slovak sk_SK
226 Slovenian sl_SI
227 Spanish es_ES
228 Swedish sv_SE
229 Thai th_TH
230 Turkish tr_TR
232 $charset - The character set to use for output documents.
234 $date_fmt - The format that the date will be displayed in. This
235 is a string that contains a number of different 'tags'.
236 Each tag consists of a % character followed by a letter.
237 Each tag represents one way of displaying a particular
238 part of the date or time. Here are some common tags:
240 %Y - four digit year (2002)
241 %y - two digit year (02)
242 %m - month of the year (01 to 12)
243 %b - short month name (Jan to Dec)
244 %B - long month name (January to December)
245 %d - day of the month (01 to 31)
246 %a - short day name (Sun to Sat)
247 %A - long day name (Sunday to Saturday)
248 %H - hour in 24 hour clock (00 to 23)
249 %I - hour in 12 hour clock (01 to 12)
250 %p - AM or PM
251 %M - minutes (00 to 59)
252 %S - seconds (00 to 59)
253 %Z - the name of the local timezone
255 $style - This is the URL of a CSS stylesheet which will be
256 used for script generated messages. This should
257 probably be the same as the one that you use for all
258 the other pages. This should be a local absolute URI
259 fragment. Set $style to '0' or the emtpy string if
260 you don't want to use style sheets.
262 $no_content - If this is set to 1 then rather than returning the
263 HTML confirmation page or doing a redirect the script
264 will output a header that indicates that no content
265 will be returned and that the submitted form should
266 not be replaced. This should be used carefully as an
267 unwitting visitor may click the submit button several
268 times thinking that nothing has happened.
270 $double_spacing - If this is set to 1 (as it is by default) then a blank
271 line is printed after each form value in the e-mail.
272 Change this value to 0 if you want the e-mail to be
273 more compact.
275 $wrap_text - If this is set to 1 then the content of any long text
276 fields will be wrapped at around 72 columns in the
277 e-mail which is sent. The way that this is done is
278 controlled by the variable $wrap_style
280 $wrap_style - If $wrap_text is set to 1 then
281 the text will be wrapped in such a way that the left
282 margin of the text is lined up with the beginning of the
283 text after the description of the field - that is to
284 say it is indented by the length of the field name
285 plus 2. If it is set to 2 then the subsequent lines
286 of the text will not be indented at all and will be
287 flush with the start of the lines. The choice of style
288 is really a matter of taste although you might find
289 that style 1 does not work particularly well if your
290 e-mail client uses a proportional font where the spaces
291 of the indent might be smaller than the characters in
292 the field name.
294 $address_style - If this is set to 0 ( or if $emulate_matts_code is set
295 to 1 ) then the address constructed for the person
296 filling in the form will be of the format
297 "$email ($realname)". If it is set to 1 then the format
298 will be "$realname <$email>".
300 $send_confirmation_mail - If this flag is set to 1 then an additional email
301 will be sent to the person who submitted the
304 CAUTION: with this feature turned on it's
305 possible for someone to put someone else's email
306 address in the form and submit it 5000 times,
307 causing this script to send a flood of email to a
308 third party. This third party is likely to blame
309 you for the email flood attack.
311 $confirmation_text - The header and body of the confirmation email
312 sent to the person who submits the form, if the
313 $send_confirmation_mail flag is set. We use a
314 Perl 'here document' to allow us to configure it
315 as a single block of text in the script. In the
316 example below, everything between the lines
318 $confirmation_text = <<'END_OF_CONFIRMATION';
324 is treated as part of the email. Everything
325 before the first blank line is taken as part of
326 the email header, and everything after the first
327 blank line is the body of the email.
329 $confirmation_text = <<'END_OF_CONFIRMATION';
330 From: email@example.com
331 Subject: form submission
333 Thankyou for your form submission.
339 Formmail is installed by copying the file FormMail.pl into your cgi-bin
340 directory. If you don't know where your cgi-bin directory is, then please
341 ask your system administrator.
343 You may need to rename FormMail.pl to FormMail.cgi. Again, your system
344 administrator will know if this is the case.
346 You will probably need to turn on execute permissions to the file. You can
347 do this by running the command "chmod +x FormMail.pl" from your command
348 line. If you don't have command line access to your web server then there
349 will probably be an equivalent function in your file transfer program.
351 You will also need to have the Perl modules under the lib/ directory in
352 this distribution installed on the machine where FormMail.pl is to run.
353 The directory structure under lib/ must be preserved. For example, if
354 you choose to install the modules under /usr/local/nms on the web
355 server then you should end up with a file heirarchy that looks like:
371 FORM CONFIGURATION
373 To make use of it, you need to write an HTML form that refers to the
374 FormMail script. Here's an example which will send mail to the address
375 'firstname.lastname@example.org' when someone submits the form:
377 <form method="post" action="http://your.domain/cgi-bin/FormMail.pl">
378 <input type="hidden" name="recipient" value="email@example.com" />
379 <input type="text" name="feedback" /><br />
380 Please enter your comments<br />
381 <input type="submit" />
384 See how the hidden 'recipient' input in the example above told formmail who
385 to send the mail to ? This is how almost all of formmail's configuration
386 works. Here's the full list of things you can set with hidden form inputs:
388 recipient - The email address to which the form submission
389 should be sent. If you would like it copied to
390 more than one recipient then you can separate
391 multiple email addresses with commas, for
394 <input type="hidden" name="recipient"
395 value="firstname.lastname@example.org,email@example.com" />
397 If you leave the 'recipient' field out of the
398 form, formmail will send to the first address
399 listed in the @allow_mail_to configuration
400 variable (see above). This allows you to avoid
401 putting your email address in the form, which
402 might be desirable if you're concerned about
403 address harvesters collecting it and sending
404 you SPAM. This feature is disabled if the
405 $emulate_matts_code configuration variable is
406 set to 1.
408 subject - The subject line for the email. For example:
410 <input type="hidden" name="subject"
411 value="From the feedback form" />
413 redirect - If this value is present it should be a URL, and
414 the user will be redirected there after a
415 successful form submission. For example:
417 <input type="hidden" name="redirect"
418 value="http://www.your.domain/foo.html" />
420 If you don't specify a redirect URL then instead
421 of redirecting formmail will generate a success
422 page telling the user that their submission was
425 bgcolor - The background color for the success page.
427 background - The URL of the background image for the success
430 text_color - The text color for the success page.
432 link_color - The link color for the success page.
434 vlink_color - The vlink color for the success page.
436 alink_color - The alink color for the success page.
438 title - The title for the success page.
440 return_link_url - The target URL for a link at the end of the
441 success page. This is normally used to provide
442 a link from the success page back to your main
443 page or back to the page with the form on. For
446 <input type="hidden" name="return_link_url"
447 value="/home.html" />
449 return_link_title - The label for the return link. For example:
451 <input type="hidden" name="return_link_title"
452 value="Back to my home page" />
454 sort - This sets the order in which the submitted form
455 inputs will appear in the email and on the
456 success page. It can be the string 'alphabetic'
457 for alphabetic order, or the string "order:"
458 followed by a comma separated list of the input
459 names, for example:
461 <input type="hidden" name="sort"
462 value="order:name,email,age,comments" />
464 If "order:" is used you must supply the names of
465 all of the fields that you want to be in the body of
466 the mail message.
468 print_config - This is mainly used for debugging, and if set it
469 causes formmail to include a dump of the
470 specified configuration settings in the email.
471 For example:
473 <input type="hidden" name="print_config"
474 value="title,sort" />
476 ... will include whatever values you set for
477 'title' and 'sort' (if any) in the email.
479 required - This is a list of fields that the user must fill
480 in before they submit the form. If they leave
481 any of these fields blank then they will be sent
482 back to the form to try again. For example:
484 <input type="hidden" name="required"
485 value="name,comments" />
487 missing_fields_redirect - If this is set, it must be a URL, and the user
488 will be redirected there if any of the fields
489 listed in 'required' are left blank. Use this if
490 you want finer control over the the error that
491 the user see's if they miss out a field.
493 env_report - This is a list of the CGI environment variables
494 that should be included in the email. This is
495 useful for recording things like the IP address
496 of the user in the email. Any environment
497 variables that you want to use in 'env_report' in
498 any of your forms will need to be in the
499 @valid_ENV configuration variable described
502 print_blank_fields - If this is set then fields that the user left
503 blank will be included in the email. Normally,
504 blank fields are suppressed to save space.
506 As well as all these hidden inputs, there are a couple of non-hidden
507 inputs which get special treatment:
509 email - If one of the things you're asking the user to fill in is their
510 email address and you call that input 'email', formmail will use
511 it as the address part of the sender's email address in the
514 realname - If one of the things you're asking the user to fill in is their
515 full name and you call that input 'realname', formmail will use
516 it as the name part of the sender's email address in the email.
518 COMMON PROBLEMS
520 * Confusion over the qw operator
522 In the configuration section at the top of FormMail, we set
523 the default list of allowed referers with this line of code:
525 @referers = qw(dave.org.uk 184.108.40.206 localhost);
527 This use of the qw() operator is one way to write lists of
528 strings in Perl. Another way is like this:
530 @referers = ('dave.org.uk','220.127.116.11','localhost');
532 We prefer the first version because it allows use to leave out
533 the quote character, but the second version is perfectly valid
534 and works exactly the same as the qw() version. You should
535 use whichever version you feel most comfortable with. Neither
536 is better or worse than the other.
538 What you must not do is try to mix the two, and end up with
539 something like:
541 @referers = qw('dave.org.uk','18.104.22.168','localhost');
543 This will not work, and you will see unexpected behavior. In
544 the case of @referers, the script will always display a
545 "bad referer" error page.
547 * Sendmail switches removed
549 In the configuration section at the top of FormMail, we set
550 the default mail program to sendmail with this code:
552 $mailprog = '/usr/lib/sendmail -oi -t';
554 This is actually two different pieces of information; the
555 location of the sendmail binary (/usr/lib/sendmail) and
556 the command line switches that must be passed to it in order
557 for it to read the list of message recipients from the
558 message header (-oi -t).
560 If your hosting provider or system administrator tells you that
561 sendmail is /usr/sbin/sendmail on your system, then you must
562 change the $mailprog line to:
564 $mailprog = '/usr/sbin/sendmail -oi -t';
566 and not:
568 $mailprog = '/usr/sbin/sendmail';
573 For support of this script please email: