"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.14c1
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
34 There are a number of variables that you can change in FormMail.pl which
35 alter the way that the program works.
37 $DEBUGGING - This should be set to 1 whilst you are installing
38 and testing the script. Once the script is live you
39 should change it to 0. When set to 1, errors will
40 be output to the browser. This is a security risk and
41 should not be used when the script is live.
43 $emulate_matts_code - When this variable is set to a true value (e.g. 1)
44 formmail will work in exactly the same way as its
45 counterpart at Matt's Script Archive. If it is set
46 to a false value (e.g. 0) then more advanced features
47 are switched on. We do not recommend changing this
48 variable to 1, as the resulting drop in security
49 may leave your formmail open to use as a SPAM relay.
51 $secure - When this variable is set to a true value (e.g. 1)
52 many additional security features are turned on. We
53 do not recommend changing this variable to 0, as the
54 resulting drop in security may leave your formmail
55 open to use as a SPAM relay.
57 $allow_empty_ref - Some web proxies and office firewalls may strip
58 certain headers from the HTTP request that is sent
59 by a browser. Among these is the HTTP_REFERER that
60 the program uses as an additional check of the
61 requests validity - this will cause the program to
62 fail with a 'bad referer' message even though the
63 configuration seems fine. In these cases setting
64 this variable to 1 will stop the program from
65 complaining about requests where no referer header
66 was sent while leaving the rest of the security
67 features intact.
69 $max_recipients - The maximum number of e-mail addresses that any
70 single form should be allowed to send copies of the
71 e-mail to. If none of your forms send e-mail to more
72 than one recipient, then we recommend that you
73 improve the security of FormMail by reducing this
74 value to 1. Setting this variable to 0 removes all
75 limits on the number of recipients of each e-mail.
77 $mailprog - The system command that the script should invoke to
78 send an outgoing email. This should be the full path
79 to a program that will read a message from STDIN and
80 determine the list of message recipients from the
81 message headers. Any switches that the program
82 requires should be provided here.
84 A $mailprog setting that works for many UNIX-like
85 hosts is:
87 $mailprog = '/usr/lib/sendmail -oi -t';
89 Some other UNIX-like hosts need:
91 $mailprog = '/usr/sbin/sendmail -oi -t';
93 If your web server lacks a sendmail binary, you can
94 use an SMTP relay instead, by setting $mailprog like
97 $mailprog = 'SMTP:mailhost.your.domain';
99 You will need to replace mailhost.your.domain with
100 the name or IP address of an SMTP server configured
101 to relay mail for the web server.
103 Your system administrator or hosting provider should
104 be able to tell you either the path to sendmail on the
105 web server or the name of a host that will act as an
106 SMTP relay for the web server.
108 $postmaster - The envelope sender address to use for all emails
109 sent by the script. This address will recieve bounce
110 messages if any of the emails cannot be delivered. If
111 in doubt, put your own email address here.
113 @referers - A list of referring hosts. This should be a list of
114 the names or IP addresses of all the systems that
115 will host HTML forms that refer to this formmail
116 script. Only these hosts will be allowed to use the
117 formmail script. This can be used to prevent others
118 from linking to FormMail.pl from their own HTML forms.
120 If you wish to turn off referer checking so that forms
121 that use this FormMail.pl can reside on any web server
122 then make this array empty, like this:
124 @referers = ();
126 @allow_mail_to - A list of the email addresses that formmail can send
127 email to. The elements of this list can be either
128 simple email addresses (like 'email@example.com') or
129 domain names (like 'your.domain'). If it's a domain
130 name then *any* address at the domain will be allowed.
132 Example: to allow mail to be sent to 'firstname.lastname@example.org'
133 or any address at the host 'mail.your.domain', you
134 would set:
136 @allow_mail_to = qw(email@example.com mail.your.domain);
138 @recipients - A list of Perl regular expression patterns that
139 determine who the script will allow mail to be sent
140 to in addition to those set in @allow_mail_to. This is
141 present only for compatibility with the original
142 formmail script. We strongly advise against having
143 anything in @recipients as it's easy to make a mistake
144 with the regular expression syntax and turn your
145 formmail into an open SPAM relay.
147 There is an implicit $ at the end of the regular
148 expression, but you need to include the ^ if you want
149 it anchored at the start. Note also that since '.' is
150 a regular expression metacharacter, you'll need to
151 escape it before using it in domain names.
153 If that last paragraph makes no sense to you then
154 please don't put anything in @recipients, stick to
155 using the less error prone @allow_mail_to.
157 %recipient_alias - A hash for predefining a list of recipients in the
158 script, and then choosing between them using the
159 recipient form field, while keeping all the email
160 addresses out of the HTML so that they don't get
161 collected by address harvesters and sent junk email.
163 For example, suppose you have three forms on your
164 site, and you want each to submit to a different email
165 address and you want to keep the addresses hidden.
166 You might set up %recipient_alias like this:
168 %recipient_alias = (
169 '1' => 'firstname.lastname@example.org',
170 '2' => 'email@example.com',
171 '3' => 'firstname.lastname@example.org',
174 In the HTML form that should submit to the recipient
175 'email@example.com', you would then set the recipient
178 <input type="hidden" name="recipient" value="2" />
180 The recipients in %recipient_alias are automatically added
181 to the allowed recipients list, so there's no need to list
182 them all in @allow_mail_to as well.
184 @valid_ENV - A list of all the environment variables that you want
185 to be able to include in the email. See 'env_report' below.
187 $locale - This determines the language that is used in the date - by
188 default this is blank and the language will probably be
189 english. The following a list of some possible values,
190 however it should be stressed that not all of these will
191 be supported on all systems and also this is not a complete
194 Catalan ca_ES
195 Croatian hr_HR
196 Czech cs_CZ
197 Danish da_DK
198 Dutc nl_NL
199 Estonian et_EE
200 Finnish fi_FI
201 French fr_FR
202 Galician gl_ES
203 German de_DE
204 Greek el_GR
205 Hebrew he_IL
206 Hungarian hu_HU
207 Icelandic is_IS
208 Italian it_IT
209 Japanese ja_JP
210 Korean ko_KR
211 Lithuanian lt_LT
212 Norwegian no_NO
213 Polish pl_PL
214 Portuguese pt_PT
215 Romanian ro_RO
216 Russian ru_RU
217 Slovak sk_SK
218 Slovenian sl_SI
219 Spanish es_ES
220 Swedish sv_SE
221 Thai th_TH
222 Turkish tr_TR
224 $charset - The character set to use for output documents.
226 $date_fmt - The format that the date will be displayed in. This
227 is a string that contains a number of different 'tags'.
228 Each tag consists of a % character followed by a letter.
229 Each tag represents one way of displaying a particular
230 part of the date or time. Here are some common tags:
232 %Y - four digit year (2002)
233 %y - two digit year (02)
234 %m - month of the year (01 to 12)
235 %b - short month name (Jan to Dec)
236 %B - long month name (January to December)
237 %d - day of the month (01 to 31)
238 %a - short day name (Sun to Sat)
239 %A - long day name (Sunday to Saturday)
240 %H - hour in 24 hour clock (00 to 23)
241 %I - hour in 12 hour clock (01 to 12)
242 %p - AM or PM
243 %M - minutes (00 to 59)
244 %S - seconds (00 to 59)
245 %Z - the name of the local timezone
247 $style - This is the URL of a CSS stylesheet which will be
248 used for script generated messages. This should
249 probably be the same as the one that you use for all
250 the other pages. This should be a local absolute URI
251 fragment. Set $style to '0' or the emtpy string if
252 you don't want to use style sheets.
254 $no_content - If this is set to 1 then rather than returning the
255 HTML confirmation page or doing a redirect the script
256 will output a header that indicates that no content
257 will be returned and that the submitted form should
258 not be replaced. This should be used carefully as an
259 unwitting visitor may click the submit button several
260 times thinking that nothing has happened.
262 $double_spacing - If this is set to 1 (as it is by default) then a blank
263 line is printed after each form value in the e-mail.
264 Change this value to 0 if you want the e-mail to be
265 more compact.
267 $wrap_text - If this is set to 1 then the content of any long text
268 fields will be wrapped at around 72 columns in the
269 e-mail which is sent. The way that this is done is
270 controlled by the variable $wrap_style
272 $wrap_style - If $wrap_text is set to 1 then
273 the text will be wrapped in such a way that the left
274 margin of the text is lined up with the beginning of the
275 text after the description of the field - that is to
276 say it is indented by the length of the field name
277 plus 2. If it is set to 2 then the subsequent lines
278 of the text will not be indented at all and will be
279 flush with the start of the lines. The choice of style
280 is really a matter of taste although you might find
281 that style 1 does not work particularly well if your
282 e-mail client uses a proportional font where the spaces
283 of the indent might be smaller than the characters in
284 the field name.
286 $address_style - If this is set to 0 ( or if $emulate_matts_code is set
287 to 1 ) then the address constructed for the person
288 filling in the form will be of the format
289 "$email ($realname)". If it is set to 1 then the format
290 will be "$realname <$email>".
292 $send_confirmation_mail - If this flag is set to 1 then an additional email
293 will be sent to the person who submitted the
296 CAUTION: with this feature turned on it's
297 possible for someone to put someone else's email
298 address in the form and submit it 5000 times,
299 causing this script to send a flood of email to a
300 third party. This third party is likely to blame
301 you for the email flood attack.
303 $confirmation_text - The header and body of the confirmation email
304 sent to the person who submits the form, if the
305 $send_confirmation_mail flag is set. We use a
306 Perl 'here document' to allow us to configure it
307 as a single block of text in the script. In the
308 example below, everything between the lines
310 $confirmation_text = <<'END_OF_CONFIRMATION';
316 is treated as part of the email. Everything
317 before the first blank line is taken as part of
318 the email header, and everything after the first
319 blank line is the body of the email.
321 $confirmation_text = <<'END_OF_CONFIRMATION';
322 From: firstname.lastname@example.org
323 Subject: form submission
325 Thankyou for your form submission.
331 Formmail is installed by copying the file FormMail.pl into your cgi-bin
332 directory. If you don't know where your cgi-bin directory is, then please
333 ask your system administrator.
335 You may need to rename FormMail.pl to FormMail.cgi. Again, your system
336 administrator will know if this is the case.
338 You will probably need to turn on execute permissions to the file. You can
339 do this by running the command "chmod +x FormMail.pl" from your command
340 line. If you don't have command line access to your web server then there
341 will probably be an equivalent function in your file transfer program.
343 FORM CONFIGURATION
345 To make use of it, you need to write an HTML form that refers to the
346 FormMail script. Here's an example which will send mail to the address
347 'email@example.com' when someone submits the form:
349 <form method="post" action="http://your.domain/cgi-bin/FormMail.pl">
350 <input type="hidden" name="recipient" value="firstname.lastname@example.org" />
351 <input type="text" name="feedback" /><br />
352 Please enter your comments<br />
353 <input type="submit" />
356 See how the hidden 'recipient' input in the example above told formmail who
357 to send the mail to ? This is how almost all of formmail's configuration
358 works. Here's the full list of things you can set with hidden form inputs:
360 recipient - The email address to which the form submission
361 should be sent. If you would like it copied to
362 more than one recipient then you can separate
363 multiple email addresses with commas, for
366 <input type="hidden" name="recipient"
367 value="email@example.com,firstname.lastname@example.org" />
369 If you leave the 'recipient' field out of the
370 form, formmail will send to the first address
371 listed in the @allow_mail_to configuration
372 variable (see above). This allows you to avoid
373 putting your email address in the form, which
374 might be desirable if you're concerned about
375 address harvesters collecting it and sending
376 you SPAM. This feature is disabled if the
377 $emulate_matts_code configuration variable is
378 set to 1.
380 subject - The subject line for the email. For example:
382 <input type="hidden" name="subject"
383 value="From the feedback form" />
385 redirect - If this value is present it should be a URL, and
386 the user will be redirected there after a
387 successful form submission. For example:
389 <input type="hidden" name="redirect"
390 value="http://www.your.domain/foo.html" />
392 If you don't specify a redirect URL then instead
393 of redirecting formmail will generate a success
394 page telling the user that their submission was
397 bgcolor - The background color for the success page.
399 background - The URL of the background image for the success
402 text_color - The text color for the success page.
404 link_color - The link color for the success page.
406 vlink_color - The vlink color for the success page.
408 alink_color - The alink color for the success page.
410 title - The title for the success page.
412 return_link_url - The target URL for a link at the end of the
413 success page. This is normally used to provide
414 a link from the success page back to your main
415 page or back to the page with the form on. For
418 <input type="hidden" name="return_link_url"
419 value="/home.html" />
421 return_link_title - The label for the return link. For example:
423 <input type="hidden" name="return_link_title"
424 value="Back to my home page" />
426 sort - This sets the order in which the submitted form
427 inputs will appear in the email and on the
428 success page. It can be the string 'alphabetic'
429 for alphabetic order, or the string "order:"
430 followed by a comma separated list of the input
431 names, for example:
433 <input type="hidden" name="sort"
434 value="order:name,email,age,comments" />
436 If "order:" is used you must supply the names of
437 all of the fields that you want to be in the body of
438 the mail message.
440 print_config - This is mainly used for debugging, and if set it
441 causes formmail to include a dump of the
442 specified configuration settings in the email.
443 For example:
445 <input type="hidden" name="print_config"
446 value="title,sort" />
448 ... will include whatever values you set for
449 'title' and 'sort' (if any) in the email.
451 required - This is a list of fields that the user must fill
452 in before they submit the form. If they leave
453 any of these fields blank then they will be sent
454 back to the form to try again. For example:
456 <input type="hidden" name="required"
457 value="name,comments" />
459 missing_fields_redirect - If this is set, it must be a URL, and the user
460 will be redirected there if any of the fields
461 listed in 'required' are left blank. Use this if
462 you want finer control over the the error that
463 the user see's if they miss out a field.
465 env_report - This is a list of the CGI environment variables
466 that should be included in the email. This is
467 useful for recording things like the IP address
468 of the user in the email. Any environment
469 variables that you want to use in 'env_report' in
470 any of your forms will need to be in the
471 @valid_ENV configuration variable described
474 print_blank_fields - If this is set then fields that the user left
475 blank will be included in the email. Normally,
476 blank fields are suppressed to save space.
478 As well as all these hidden inputs, there are a couple of non-hidden
479 inputs which get special treatment:
481 email - If one of the things you're asking the user to fill in is their
482 email address and you call that input 'email', formmail will use
483 it as the address part of the sender's email address in the
486 realname - If one of the things you're asking the user to fill in is their
487 full name and you call that input 'realname', formmail will use
488 it as the name part of the sender's email address in the email.
490 COMMON PROBLEMS
492 * Confusion over the qw operator
494 In the configuration section at the top of FormMail, we set
495 the default list of allowed referers with this line of code:
497 @referers = qw(dave.org.uk 126.96.36.199 localhost);
499 This use of the qw() operator is one way to write lists of
500 strings in Perl. Another way is like this:
502 @referers = ('dave.org.uk','188.8.131.52','localhost');
504 We prefer the first version because it allows use to leave out
505 the quote character, but the second version is perfectly valid
506 and works exactly the same as the qw() version. You should
507 use whichever version you feel most comfortable with. Neither
508 is better or worse than the other.
510 What you must not do is try to mix the two, and end up with
511 something like:
513 @referers = qw('dave.org.uk','184.108.40.206','localhost');
515 This will not work, and you will see unexpected behavior. In
516 the case of @referers, the script will always display a
517 "bad referer" error page.
519 * Sendmail switches removed
521 In the configuration section at the top of FormMail, we set
522 the default mail program to sendmail with this code:
524 $mailprog = '/usr/lib/sendmail -oi -t';
526 This is actually two different pieces of information; the
527 location of the sendmail binary (/usr/lib/sendmail) and
528 the command line switches that must be passed to it in order
529 for it to read the list of message recipients from the
530 message header (-oi -t).
532 If your hosting provider or system administrator tells you that
533 sendmail is /usr/sbin/sendmail on your system, then you must
534 change the $mailprog line to:
536 $mailprog = '/usr/sbin/sendmail -oi -t';
538 and not:
540 $mailprog = '/usr/sbin/sendmail';
545 For support of this script please email: