Using the mail.form application to receive input from a Web Form
How to Use University Web Forms
The instructions below describe how to create a university html Web form (for Central UNIX Web server accounts) for gathering input from Web users to be emailed to a Cal Poly email account.
Getting From a Web Form to You - How the Form Input Process Works
In order for Web form input to be returned to you, there has to be a program available to the Central Unix Web server to handle the input. The mail.form application has been developed by ITS to handle this task. It accepts the input from your form, formats it for email delivery, then emails it to a valid Cal Poly email address. The mail.form program needs to be referenced in the HTML of your Web form code along with the email address it is to send the form input to. Other details are needed as well (see below).
What Your Users Can Expect to See When Using Your Web Form
Using a correctly configured Web form, a user can enter information into the fields of your form. When the user submits the form, they will be presented with a university visual verification page to complete the submission of the form. Upon completion of the visual verification page, the mail.form application takes the user's information and emails it to a Cal Poly email address.
Notifying Your Users
Add the following notification text to your web form page just above the submit button to alert your users that they will be presented with the visual verification page:
After clicking the Submit button the university visual verification page will be displayed. Please respond to the question to complete the submission of your request.
The visual verification feature has been implemented to improve security and to reduce potential abuse of Cal Poly's e-mail system through use of automated SPAM techniques.
Information Technology Services has tried to design this process to be accessible to everyone, including persons with disabilities. ITS requests of departments using the mail.form application to assist users who may have difficulty using an online form created by the department
For further information on visual verification (aka CAPTCHA images), please see the Wikipedia article https://en.wikipedia.org/wiki/CAPTCHA
Making University Web Forms Accessible (ADA Compliant)
When developing a form for an Official Cal Poly Web page, you must make the form Web Accessible. Several resources are provided for your convenience:
- The Cal Poly Accessibility site offers Web Accessibility information
- The WebAIM project provides techniques for setting up and Creating Accessible Forms.
Please note that ITS provides only this documentation in support of setting up the Web form (mail.form application) feature on user's accounts.
Instructions for Setting Up a University Web Form
How do I create a form?
We do not attempt to teach you all about forms here. To find out how to create forms, do a Google search for online documentation. Also see the following:
- The WebAIM projects provides excellent techniques for Creating Accessible Form pages.
- The HTML Code Tutorial provides additional information on setting up forms
Where can I get a form template to start with?
We have put code for an example input form on-line for you to start out with.
What do I need to include in my form to use the mail.form service?
For use with the mail.form program, your form needs to include certain lines which reference the mail.form program and give it the information it needs for mailing. The necessary lines are explained below. Let's assume your Central UNIX userid is "jdoe".
GOTCHA: Name variables such as "Location:" use the colon (:) as mail header information by the mail.form program. DO NOT use colons in other input names unless indicated below.
GOTCHA: Look out for the lines that are absolutely required. They're indicated below.
<form method="post" action="https://www.calpoly.edu/cgi-bin/mail.form">
Begin the form element within your Web form by inserting the opening
<form> tag as shown above which tells the Web server to use the mail.form application to process the HTML form. The closing
</form> tag is shown at the bottom of this page. All the input tags and text to be contained within your form must be located between the opening
<form> and closing
Optional - Recommended
<input name="Location:" type="hidden" value="http://www.calpoly.edu/~jdoe" />
The value above is the Web page (URL) that you want to be presented to the user after the form has been submitted. If you leave this out, the user will be presented with a generic acknowledgement page indicating the form has been submitted.
<input name="To:" type="hidden" value="firstname.lastname@example.org" />
The value above is the full address that the form content will be mailed to (email@example.com), in this case, "
firstname.lastname@example.org". This is required! The mail.form script handles all email addresses that end with calpoly.edu.
The value element must be an email address within the Cal Poly domain and of the form userid@*.calpoly.edu (where * is a mail machine name). For example email@example.com and firstname.lastname@example.org are valid. If you have additional questions regarding OCS email accounts, please contact the Cal Poly Service Desk at 756-7000.
Example of Using Multiple Email Addresses
<input name="To:" type="hidden" value="email@example.com, firstname.lastname@example.org, email@example.com" />
If you would like to email more than one user, you should separate each name with commas. At least one username is required.
Example of an Incorrect Email Address
<input name="To:" type="hidden" value="firstname.lastname@example.org" />
The example above WILL NOT WORK!
The value (in this case "
email@example.com") associated with To: can only contain Cal Poly UNIX usernames. In other words, you can NOT email users outside of the Cal Poly domain.
Recommended - Optional
<input name="From:" type="hidden" value="The User of My Nifty Form" />
The value above can be whatever you want the From: field in the email to look like it when it is sent by the mail.form application.came from. If you leave it out, this value will default to "WWW User."
Recommended - Optional
<input name="Subject:" type="hidden" value="Whatever You Want" />
The value above will be placed as the subject line on the mail message that is created by the mail.form program. If you leave it out, the Subject line defaults to "WWW Form Values".
<input name="X-Comment:" type="hidden" value="Your Name and the web address of this form" />
Put your name and the web address of the form you are creating here for tracking or trouble-shooting (if you use more than one form, you will want to readily identify the location of the form).
Example of Using the X-comment line
<input name="X-comment:" type="hidden" value="John Doe, http://www.calpoly.edu/~jdoe/form.html" />
The value in the X-comment statement will display as a line in the header of the email message that is created by the mail.form application.
Recommended - Example Input Fields
The following are sample lines of code for form fields that can be used on simple Web form. You will need some form field in your Web form for users to input their information.
<label for="username">Your name:</label>
<input type="text" name="username" id="username" />
<label for="email">Your email address: </label>
<input type="text" name="email" id="email" />
<label for="comments">Type your comments in the text area below </label>
<textarea name="comments" id="comments" cols="50" rows="10"></textarea>
<input type="submit" value="Submit your Feedback" />
You will need the "submit" line to create a submit button for the user to submit your form, thereby handing it off to the mail.form application. The value is optional, however it is strongly recommended that the word "submit" be used in the text of the button.
</form> tag is the required closure element for the opening
<form...> tag that we opened at the beginning of this tutorial. This line is required to close off the form.
That should do it. You can test your Web form after it is uploaded to your Central UNIX Web account (see Uploading to Central UNIX for details).
Please note that ITS provides only this documentation in support of setting up the Web form (mail.form application) feature on Central UNIX Web accounts.