Mail_Form

Mail_Form composes an email from the contents of submitted HTML forms.

It can be used to allow you to write HTML forms and to have the results emailed to you -- without you needing to write your own CGI program for each form.

To use Mail_Form, begin your form with something like

  <form method="post"
        action="/cgi-bin/utils/mailform"
        enctype="application/x-www-form-urlencoded">

Your HTML form must also include certain form elements that tell Mail_Form what to email and to whom. This is done with form elements named "mailform_*". Mail_Form is very customizable depending on how these elements are defined, but can also run when as few as two of the elements are defined (see usage notes below for which elements are required). Your HTML form can also ask the user to fill in some of this information.

mailform_* form elements

mailform_name_to: the To: display name
mailform_email_to: the To: email address (or local-part only) (To: mailform_name_to <mailform_email_to>
mailform_email_to_host: the To: hostname (To: mailform_name_to <mailform_email_to@mailform_email_to_host>)
mailform_name_from: the From: display name
mailform_email_from: the From: email address (or local-part only) (From: mailform_name_from <mailform_email_from>
mailform_email_from_host: the From: hostname (From: mailform_name_from <mailform_email_from@mailform_email_from_host>)
mailform_subject: the Subject:
mailform_fields: comma separated list of form elements to include in the email. The email message will consist of lines containing "element_name: element_value"
mailform_fields_skip_blank: do not include an item from mailform_fields in the output if its value is empty (blank)
mailform_email_template: URL from which to retrieve template for email body. (Used instead of mailform_fields.) The URL must be fully qualified (e.g. http://www.example.com/path_to_template.txt). This element may also be a keyword for a pre-defined template within Mail_Form. Desired variables are in template surrounded by a pair of %'s, e.g. %%mailform_email_from%%. Templates can include any form element; they are not restricted to mailform_* form elements.
mailform_url_success: URL to which to redirect user after processing. Must be a fully-qualified URL, e.g. http://www.example.com/form_submitted.html
mailform_url_failure: URL to which to redirect user after failure. Must be a fully-qualified URL, e.g. http://www.example.com/submission_failure.html
mailform_show_submission: (1 (true) or 0 (false)) show submitted form data to user
mailform_success_refresh: length of time to display submission before refreshing page to mailform_url_success
mailform_http_referer: URL by which submitter came to HTML form (which was then submitted to Mail_Form) This is for use if multiple pages on a site link to the same HTML page containing the HTML form and you want to know from where each user came. Your HTML form can fill in this value using a scripting language such as JavaScript or PHP.

      <form method="post"
               action="/cgi-bin/utils/mailform name=my_form_name"
               enctype="application/x-www-form-urlencoded">
      ...
      <input type=hidden name=mailform_http_referer>
      <script language=Javascript><!--
          document.my_form_name.mailform_http_referer.value = document.referrer;
      //--></script>
      ...
      </form>


      <form method="post"
               action="/cgi-bin/utils/mailform"
               enctype="application/x-www-form-urlencoded">
      ...
      <?php
	  echo '<input type=hidden name=mailform_http_referer ' .
	       'value="' . htmlspecialchars($_SERVER[HTTP_REFERER]) .
	       "\">\n";
      ?>
      ...
      </form>

Usage notes

The only REQUIRED field is mailform_email_to, although the Mail_Form won't produce anything useful unless at least one of mailform_fields or mailform_email_template is set, too.
Set mailform_email_to as local-part of address and mailform_email_to_host to domain instead of putting the complete address in mailform_email_to so as not to list a complete email address that spammers can filtch from the HTML. Same for mailform_email_from.
mailform_email_to must be an address that is deliverable locally to the server on which Mail_Form is running. This is so that spammers can not use Mail_Form to send out anonymous spam. What this means to you is that you may not use your @yahoo address as mailform_email_to. You can use your_account@your.isp.com or your_account@your.domain.com if your.isp.com hosts your.domain.com and the mail for your.domain.com is handled by the servers running Mail_Form.
In addition to being the URL from which the email template may be retrieved, mailform_email_template can be a keyword for a pre-defined email template. Currently, the only pre-defined template has the keyword 'message' and the complete body of the email message contains solely the value of the HTML form element named 'message'. (The template is simply a file containing only "%%message%%".)

Example

  <form method="post"
        action="/cgi-bin/utils/mailform"
        enctype="application/x-www-form-urlencoded">
  <input type=hidden name=mailform_fields
         value="favorite_color, favorite_game">
  <input type=hidden name=mailform_email_to
         value="devnull">
  <input type=hidden name=mailform_email_to_host
         value="example.com">
  <input type=hidden name=mailform_subject
         value="my favorites">
  What are your favorites?
  <hr>
  Favorite color: <input name=favorite_color><br>
  Favorite game:  <input name=favorite_game><br>
  <input type=submit>
  </form>

If the user fills out favorite_color as 'purple' and favorite_game as 'peek-a-boo', Mail_Form will produce the following email when the form is submitted:

  To: devnull@example.com
  Subject: my favorites

  favorite_color: purple
  favorite_game: peek-a-boo

If mailform_email_template were used instead of mailform_fields, as in

  <input type=hidden name=mailform_email_template
         value="http://www.example.com/favorites.template.txt">

and the template file looked like this

  I just wanted to tell you that my favorite color is %%favorite_color%% and
  that my favorite game is %%favorite_game%%.

then Mail_Form would produce this email:

  To: devnull@example.com
  Subject: my favorites

  I just wanted to tell you that my favorite color is purple and
  that my favorite game is peek-a-boo.

Mail_Form is a Perl module (Mail_Form.pm) that is designed for use with mod_perl under Apache, although it also works as a CGI program under any web server (that supports Perl CGI programs).