CGI Program: generic-inbox

Description

generic-inbox.pl is a general purpose script that gathers data from a web form and performs one or both of these functions:

send data via email
append data to a file

This script is typically used in web forms that allow users to register for an event (e.g. fun run), to request information, to order a T-shirt, and for a variety of other purposes.

Email destinations are limited to local addresses

Since March 24th, 2003 this script will only send mail to addresses in the columbia.edu and barnard.edu domains. This limit was imposed to prevent the script being used to send mass mail anonymously. If both local and outside addresses are specified on the web form then the local addresses will be used and the outside addresses will be ignored.

Spam protection provided via captcha

Starting December 10, 2013, spam protection will be provided to all forms using generic-inbox.pl via a captcha challenge.

Sample web form

Look here for a sample web form that uses the generic-inbox script. After viewing it, you can save that document in your public_html directory and edit as appropriate. Or, instead of using a separate document to access the inbox program, you can insert the form in an existing document. Just copy everything from <form> to </form> and then edit as necessary.

Radio buttons good, checkboxes bad

You should not use checkboxes on your form since their value is only included when they are checked. Radio buttons can be used if there is a default value: i.e. one of the buttons is initially "checked" in your form.

Hidden variables

The form contains hidden variables that are passed to the CGI script along with the data typed by the user. These variables are used to control the actions of the script. In our example we have the following:


<input type=hidden name=mail_dest value="aaa888@columbia.edu">
<input type=hidden name=mail_cc   value="nobody@columbia.edu">
<input type=hidden name=cc_sender value="true">
<input type=hidden name=file_dest value="~aaa888/inbox">
<input type=hidden name=ack_link  value="/~aaa888/thankyou.html">
<input type=hidden name=subject   value="testing the inbox function">
<input type=hidden name=echo_data value="true">
<input type=hidden name=format    value="col_align">
<input type=hidden name=timestamp value="true">
<input type=hidden name=reqfields value="rmail,address,city,state,zip">

The purpose of each variable is explained below.

Appending to a file

file_dest

If the form contains a variable named file_dest, the data will be appended to the file specified by that variable. If this variable is missing or null the data will not be appended to a file. The script will only write to a file in a user's web_allow directory, which must be a subdirectory of a user's home directory, not part of the official web space in /www/data. In the above example the file_dest variable is set to ~aaa888/inbox which means the data will be appended to this file:

~aaa888/web_allow/inbox

Note that the words "web_allow" are not included in the value of the file_dest variable, it contains only ~aaa888/inbox.

You must create the web_allow directory, and you must create the inbox file if you want to use this feature. For security reasons the following requirements are imposed by this script.

Your web_allow directory must be in your personal home directory.
Your home directory must not be group writable or world writable.
Your web_allow directory must not be group writable or world writable.
The inbox file must exist and must be owned by you.

Use these commands to create the web_allow directory and the inbox file.

$ mkdir ~/web_allow
$ touch ~/web_allow/inbox

reqfields

Set the reqfields variable to a list of the required fields on your form. The user will not be able to submit the form until all required fields have been entered. You can include rmail as one of the required fields, which has the same effect as setting rmailreq in your form.

rmailreq

Set the rmailreq variable true if you want to force the user to enter their email address in the form before submitting it. Otherwise the email address is optional. Note that the email address will not be validated, so you can't be sure they are who they say they are.

Sending Email

mail_dest

Set the mail_dest variable to your email address if you want the form data mailed to you. You can put multiple addresses here, separated by commas. If this variable is missing, or null, the data will not be mailed. Only columbia.edu and barnard.edu addresses will be accepted. You can omit the "@columbia.edu" in each address since that is the default host name.

mail_cc

Additional email destinations can be specified using the mail_cc variable. These recipients will appear in the CC field of the email message, instead of the TO field. You can enter a single email address, or multiple addresses separated by commas. This variable is ignored if the mail_dest variable is missing or null.

cc_sender

Set the cc_sender variable true if the user who is submitting the form should receive a copy of the message. In that case they will receive a CC of the message, as long as they filled in their email address in the rmail field.

subject

Set the subject variable to the text string that should be used as the subject of your form mail, for example: "response to your political survey". When you receive form mail you will know immediately which document they are responding to by looking at the subject.

rmail field

The rmail field should be included in your form if you want to give the user an opportunity to enter their email address. The user can leave the rmail field blank unless you made it a required field by setting the rmailreq variable true, or by including rmail in the reqfields list.

rmailreq

As described above the rmailreq variable should be set true if the rmail field is a required field.

reqfields

As described above the reqfields variable should contain a list of required fields.

Variables that affect the acknowledgement page

ack_link

If the ack_link variable is specified it should contain the URL of a document that will be displayed instead of the default acknowledgement screen. You can use this feature to point the user at another web document after they have submitted the form. This acknowledgement page should say "Thank you for participating in this survey", or "Thanks for registering for the Fun Run", or whatever is appropriate.

If ack_link is not specified then the default acknowledgement page will be displayed. Included in the display are the contents of the file_dest and mail_dest variables so you can see where the data was sent.

echo_data

If the ack_link variable is not specified and the echo_data variable is true, the form data will be displayed on the acknowledgement screen. This feature is available to help you verify that your form is working correctly. If echo_data is missing or null you will get an acknowledgment screen but it will not display any data. The echo_data variable is ignored if the ack_link variable is set.

Selecting the data format

default format

When format is blank or unspecified the default output format is used for mail and for the inbox: one field per line with equal signs separating the field names and field values. The timestamp variable defaults to 'true' but timestamps can be suppressed by setting timestamp to 'false'.

begindata=Tue Jul 27 17:10:04 1999 ----------------------------------------
seldate=Sep 9, 1995 
seltype=apple
seltext=Hi there.
rmail=aaa888@columbia.edu
address=Watson Hall
city=New York
state=NY
zip=10025

col_align format

When format is set to col_align field names and values are displayed in two columns when sent via mail or appended to an inbox. The timestamp variable defaults to 'true' but timestamps can be suppressed by setting timestamp to 'false'.

    Time submitted            Fri Jul 16 14:12:53 1999
    seldate                   January
    seltype                   apple
    seltext                   Hi There.
    rmail                     aaa888@columbia.edu
    address                   Watson Hall
    city                      New York
    state                     NY
    zip                       10025

tab_delim format

When tab_delim format is specified the data values for each submision are appended to your inbox, on one line, separated by tabs. In this format the field names are not included. For example:

Sep 16, 1995    apple   Hi there. aaa888@columbia.edu        Watson Hall     New York        NY      10023

This format makes it easy to import the data into a spreadsheet application. All tabs typed by the user will be converted to spaces so the only tabs in your inbox will be the field separators. email will be sent in the default format, only the inbox file will have the tab deliminated data. The timestamp variable defaults to 'true' but timestamps can be suppressed by setting timestamp to 'false'.

html_table format

The output is sent with html code to present a two-column table. The first column contains the field names and the second column contains the field values. If the person filling in the form left any item blank, the words "user left blank" are inserted into that table slot. The timestamp variable defaults to 'false' but timestamps can be included by setting timestamp to 'true'.

<table border=1> <tr><td>seldate</td><td>Sep 16, 1995</td></tr> <tr><td>seltype</td><td>apple</td></tr> <tr><td>seltext</td><td>Hi there.</td></tr> <tr><td>rmail</td><td>aaa888@columbia.edu</td></tr> <tr><td>address</td><td>(user left blank)</td></tr> <tr><td>city</td><td>New York</td></tr> <tr><td>state</td><td>NY</td></tr> <tr><td>zip</td><td>10025</td></tr></table>

When inserted into an html document the table would look like this:

seldate Sep 16, 1995

seltype apple

seltext Hi there.

rmail aaa888@columbia.edu

address (user left blank)

city New York

state NY

zip 10025

html_row format

The output is sent with html code to present a single table row. The variable names are not included, only the values. The <table> </table> tags are not included. If the person filling in the form left any item blank, the words "user left blank" are inserted into that table slot. The timestamp variable defaults to 'false' but timestamps can be included by setting timestamp to 'true'.

<tr><td>Sep 16, 1995</td><td>apple</td><td>Hi there.</td>
<td>sue@columbia.edu</td><td>(user left blank)</td>
<td>New York</td><td>NY</td><td>10025</td></tr>

timestamp

If the form contains a variable named timestamp and the value is true, the time of submission of the form will be included in the email message and in the data appended to the inbox. Timestamps are included by default when the output format is default, col_align, or tab_delim.

Scrolling text fields

The example uses a textarea field that allows the user to type past the right margin using most browsers. The text will scroll to the left, allowing them to keep typing. When they hit <RETURN> the cursor moves to the next line.

The textarea field in the example is 3 rows high and 60 columns wide. You might want to display a text area of a different size. A smaller text area will encourage shorter responses.

You can insert prompting text inside the textarea field, between the <textarea> and </textarea> tags. In the example we use the prompting text "Dear Mr. Jones,".

Replying to web mail

When someone uses your form to send you mail you will receive an email message. In that message, the From: field will contain "www" and the Reply-To: field will contain their email address, if they typed it in the form. You should be aware that they might have typed someone else's address in that field, so beware of phony messages. When you reply to that message your mail program should automatically use the address in the Reply-To: field. If the user sends you mail without a Reply-To: field you will be unable to reply to them.

Last modified 12/03/13 15:35
Academic Information Systems
Columbia University Help Line: 212 854.1919
Email: webmaster@columbia.edu

seldate	Sep 16, 1995
seltype	apple
seltext	Hi there.
rmail	aaa888@columbia.edu
address	(user left blank)
city	New York
state	NY
zip	10025