Email.cgi version 5.0.3

Email.cgi is looking for a new home.

For a long time I was able to say, "Email.cgi, since 1994. One of the older, if not the oldest, continually supported CGI scripts for the Macintosh. Still free." Unfortunately, those times are coming to an end. If you would like to take over the maintenance of email.cgi and call it your own, then please don't hesitate to drop me a line.

I wrote email.cgi some time in 1994. It's purpose, at that time, was to fill a niche left open by MacWeb, a Macintosh-based Web browser that didn't support mailto links. Since then the application grew to allow the contents of just about any sort of HTML form to be sent to one or more email addresses. Email.cgi served me and a host of others quite well for a relatively long period of time.

A number of things have changed making it difficult for me to support email.cgi. First, I recently had a hardware failure, and the CPU I used to use to demonstrate email.cgi broke. I do not plan on getting a replacement. Second, email.cgi is designed to run via AppleEvents sent from an HTTP server. With the advent of Mac OS X, the default HTTP server is now Apache, and Apache does not send AppleEvents. While I can incorporate a piece of middle ware allowing AppleEvents to be sent from Apache to email.cgi, the middle ware I am aware of is not free. I want email.cgi to be free as well as it's supporting tools. Third, frankly, I have lost interest. Ten years is a long time to support something, and it is now time to pass the torch. As the Internet becomes more ubiquitous, so have crackers and other deviants. This raises issues surrounding spam and the hijacking email.cgi for dubious purposes. These issues are real and significant, but they are not issues I desire to attack. Call me lazy.

In any event, if you are interested in taking email.cgi on then please email me. "Email.cgi. Free to a good home."

Introduction

The purpose of email.cgi is to extract the contents of an HTML form and send those contents to one or more email addresses.

Email.cgi supports carbon copied and well as blind carbon copied messages. It allows for required fields giving Webmasters to ability to mandate data-entry for specific inputs before processing will be completed. Email.cgi has two types of output: output to an email address and output in the form of HTML documents. Both types are highly customizable. No configuration is necessary to the program itself; all customizations are done through the creation of HTML forms. Email.cgi captures and optionally returns the bits of information sent by Web browsers (environment variables) describing their operating environment. The source code for email.cgi is freely available so you can make changes as you see fit.

Using email.cgi writers of HTML documents can create things such as but not limited to: surveys, order forms, requests for more information, front-ends to mailing list commands, comment forms, purchase requests, votes and polls, etc. Combined with your desktop email program's filtering functions you will be able to use email.cgi to process mailing list requests or return automated email replies to specific questions.

Email.cgi should be completely backwards compatible with older versions of the program. The forms you created using the older versions of email.cgi should work just fine with this newer version. The only difference you will see is the format of the program's output files.

If you know how or want to learn how to write HTML forms, and you can meet the hardware and software requirements listed below, then you can use email.cgi.

Enjoy email.cgi. Have fun with it.

Requirements

Email.cgi is an AppleScript CGI application for Macintosh computers. It requires the following hardware and software:

  1. A Macintosh computer connected to the Internet.
  2. AppleScript, a scripting language almost certainly already installed on your Mac.
  3. A Web (HTTP) server supporting common gateway interface (CGI) scripts. Just about all Web servers support CGI scripts. MacHTTP, WebSTAR, NetPresenz, Quid Pro Quo, as well as Personal Web Sharing all work just fine.
  4. Access to a local, simple mail transfer protocol (SMTP) server. Believe it or not, you've probably got one of these.
  5. MondoMail, an AppleScriptable SMTP mailing agent, also available locally.
  6. Parse CGI OSAX, an AppleScript extension simplifying the process of extracting form elements into programing variables, also available locally.
  7. And of course, the email.cgi program itself.

Installation

Installation is not difficult. Here's how:

  1. Get your Web server up and running. Describing how to do this is beyond the scope of these instructions.
  2. Download MondoMail, save it anywhere on your hard disk, and note it's location.
  3. Download Parse CGI OSAX, drop it on a your closed System folder, and it should be automatically saved in your Scripting Additions Folder. (If the computer did not tell you where it was putting the OSAX, then it probably did not put it in the right place and you will have to move it to the Scripting Additions Folder manually.)
  4. Download email.cgi and save it anyplace where it will be available to your Web server. Often times there will be a folder named "scripts" or "cgi-bin" for the purposes of things like email.cgi.
  5. Double-click on email.cgi. It might ask you for the location of MondoMail. If so, then locate MondoMail.

Congratulations! You are now ready to write your first email.cgi form.

Required input tags and the simplest form

To use email.cgi you write HTML forms making sure their action attributes point to email.cgi and their method attribute is POST. Additionally, the program requires, at the very least, three specifically named input tags in order to function correctly: to_address, from_address and mailer. These input tags are defined below:

  1. to_address - This is an email.cgi required field. All email.cgi forms must contain an input tag with this name, and the value of the input must be a valid email address (or addresses). The type of this input will most likely be hidden. For example, if I wanted the contents of an email.cgi form to be sent to me, then I would create a form with the following input tag:

    <input type="hidden" name="to_address"
    value="eric_morgan@infomotions.com">

    The value of this input tag is not limited to a single email address; you can have email.cgi send its output to multiple email addresses by stringing together multiple values delimited by commas. For example, I could send the output of an email.cgi form to two of my email accounts by using the following input tag:

    <input type="hidden" name="to_address
    value="eric_morgan@infomotions.com,ericmorgan@aol.com">

    You are not limited to the input type of hidden for this required variable. Input types like radio buttons, check-boxes, scrolling lists, pop-up menus, and simple text inputs will work correctly as long as the input is valid.

  2. from_address - This is an email.cgi required field. The value for this input tag is a valid email address. Email.cgi uses the contents of this tag as the email address of the person who is sending email. For example:

    <input type="text" name="from_address">

    If users of your forms supply an invalid email address, then you are up the creek; there is little you can do to prevent people from entering invalid values in this field.

  3. mailer - This is an email.cgi required field. All email.cgi forms must contain an input tag with this name, and the value of the input must be the Internet name or IP address of a valid, accessible Simple Mail Transfer Protocol (SMTP) server. You can most likely discover the Internet name or IP address of your local SMTP server by examining the preferences of your desktop email program because your email program requires an SMTP server in order to function correctly. This input tag will almost always be hidden and an example includes the following:

    <input type="hidden" name="mailer" value="mail.infomotions.com">

The form below illustrates and demonstrates just about the simplest possbile email.cgi form. Once you submit it you should get the default email.cgi output that includes all the variables sent to the form as well as the "free environment variables" sent by your browser.

<!-- an action statement pointing to email.cgi using the POST -->
<form action="./email.cgi" method="POST">

<!-- who is to get the mail with to_address, a required field -->
to_address: <input type="text" name="to_address"
value="eric_morgan@infomotions.com">
<br />

<!-- who is sending the mail with from_address, a required field -->
from_address: <input type="text" name="from_address">
<br />

<!-- address of your SMTP mailer, a required field -->
mailer: <input type="text" name="mailer" value="mail.infomotions.com">
<br />

<!-- add a submit button -->
<input type="submit" value="submit">

<!-- finish the form -->
</form>

Many inputs

Of course you will want to create forms containing a variety of inputs such a check boxes, radio buttons, text inputs, etc. The form below includes a few of these input types and again returns the default output.

<form action="./email.cgi" method="POST">

<!-- include to_address and mailer, but hide
them since the end-users don't need to know -->

<input type="hidden" name="to_address" value="eric_morgan@infomotions.com">
<input type="hidden" name="mailer" value="mail.infomotions.com">

<!-- let's do a pizza delivery, first the size using radio buttons -->
size:
<input type="radio" name="size" value="small">small
<input type="radio" name="size" value="medium">medium
<input type="radio" name="size" value="large" checked>large
<input type="radio" name="size" value="extra large">extra large
<br />

<!-- now some toppings with check boxes -->
toppings:
<input type="checkbox" name="topping" value="mushrooms" checked>mushrooms
<input type="checkbox" name="topping" value="onions">onions
<input type="checkbox" name="topping" value="peppers">peppers
<input type="checkbox" name="topping" value="peperoni" checked>peperoni
<br />

<!-- don't forget their from_address, a required field -->
email address: <input type="text" name="from_address">
<br />

<!-- get their telephone number using simple text input -->
telephone number: <input type="text" name="telephone" value="1 800 555 1212">
<br />

<input type="submit" value="submit">

</form>

User required inputs

Often times you will want to require end-users to supply various inputs. This function is supported by email.cgi when you prepend the name of a form's input tag with user_required_. For example, if you want to require the end-user to supply their first name, then one of your input tags might look like this:

<input type="text" name="user_required_firstname">

When submitted, the following form, in its default state, will return the default error message. When the form is submitted and every field includes a value, the default email.cgi output will be returned.

<form action="./email.cgi" method="POST">

<!-- required fields -->
<input type="hidden" name="to_address" value="eric_morgan@infomotions.com">
<input type="hidden" name="mailer" value="mail.infomotions.com">

<!-- get two simple inputs and make them all required -->
first name: <input type="text" name="user_required_firstname"><br />
last name: <input type="text" name="user_required_lastname"><br />

<!-- again, don't forget the from__address -->
email address: <input type="text" name="from_address"><br />

<input type="submit" value="submit">

</form>

Unwrapping input

Email.cgi allows you to have the return characters removed from the contents of your form. This is called unwrapping and proves useful when using the <textarea></textarea> input tags. To unwrap the contents of your inputs include unwrap_ anywhere in its name.

The following form includes two <textarea></textarea> input tags. When submitted the default email.cgi output will be returned. The contents of the first <textarea></textarea> input tag will not be unwrapped, the second one will be unwrapped.

<form action="./email.cgi" method="POST">
<input type="hidden" name="to_address" value="eric_morgan@infomotions.com">
<input type="hidden" name="mailer" value="mail.infomotions.com"> 

<!-- get the user's email address -->
<p>email address: <input type="text" name="from_address"></p>

<!-- tell me a story, without unwrapping the text -->
<p>a story:<br />
<textarea rows="7" cols="50" name="a story">
There lives a young girl in Lancaster town,
Whose hair is shiny pale green.
She lives at the bottom of Morgan's farm pond,
So she's really too hard to be seen. 
</textarea>
</p>

<!-- unwrap this text by using unwrap_ in the name
of the variable, "unwrap_another story"-->
<p>another story: <br />
<textarea rows="7" cols="50" name="unwrap_another story">
Once upon a time there were three bears: Daddy
Bear, Mommy Bear, and Baby Bear. They lived in a
nice house in the forest, and one summer day they
went for a walk. Along came a girl named Goldy
Locks. She discovered the bear's empty house and
decided to make a mess. The bears came home, and
they were angry. Goldy Locks rans away. The end.
</textarea>
</p>

<input type="submit" value="submit"> 
</form>

Special variables

There are a number of special variable names you can give input tags in order to enhance processing. These variable names include: debugMode, subject, cc, bcc, and redirect. Each of these variables and their functions are described below, but do not use these variable names unless you want to have email.cgi perform these functions:

  1. debugMode - An input tag with this name and given any value will cause email.cgi to return a list of all its given inputs and then exit. A tag with this name is usually hidden and used only for validation purposes. For example:

    <input type="hidden" name="debugMode" value="1">

    Remember, the value of this tag can be any value other than empty ("") in order to function correctly.

  2. subject - The value of an input field with this name becomes the subject of the email message being sent by email.cgi. Often times you will want to make this a hidden field so users cannot edit it and you can filter your incoming email.cgi output accordingly. For example:

    <input type="hidden" name="subject" value="problem report">

    If you do not supply an input tag named subject in your forms, then email.cgi defaults the value of subject to "Email.cgi output".

  3. cc - An input tag given this name "carbon copies" email.cgi output to sets of one or more email addresses. Just like the required input tag to_address, the value of input tags named cc must contain one or more valid email addresses. If multiple carbon copied email addresses are desired, then you must concatonate them together with commas. Examples include:

    <input type="hidden" name="cc" value="eric_morgan@infomotions.com">

    or

    <input type="hidden" name="cc"
    value="ericmorgan@aol.com,emorgan@sunsite.berkeley.edu">

    Only one input tag named cc is allowed per email.cgi form.

  4. bcc - Input tags with this name work just like the input tags for tags named cc except values are used for "blind carbon copied" email messages. An example includes:

    <input type="hidden" name="bcc" value="eric_morgan@infomotions.com">

    Only one input tag named bcc is allowed per email.cgi form.

  5. redirect - The provision of an input tag named redirect is one way email.cgi can return the end-user an HTML page other than the default email.cgi output. The default email.cgi output is functional, but not very aesthetically pleasing. By assigning a full URL to the value of an input tag named redirect, email.cgi will process the form's content and tell the end-user's browser to go to the a pre-defined HTML page written as a results page:

    <input type="hidden" name="redirect"
    value="http://www.infomotions.com:81/cgi-bin/redirect-page.html">

    Only one input tag named redirect is allowed per email.cgi form.

The forms below illustrate and demonstrate the use of these special variables. This first form demonstrates the use of debugMode.

<form action="./email.cgi" method="POST">

<input type="hidden" name="to_address" value="eric_morgan@infomotions.com">
<input type="hidden" name="mailer" value="mail.infomotions.com">

<!-- (hint, hint) -->
<input type="hidden" name="from_address" value="mr_debug@errorsrus.com">

<!-- turn debug mode on or off -->
debug mode: 
<input type="radio" name="debugMode" value="1" checked>on 
<input type="radio" name="debugMode" value="">off<br> 

<input type="submit" value="submit">

</form>

This second form illustrates and demonstrates the use of subject, cc, and bcc.

<form action="./email.cgi" method="POST">

<input type="hidden" name="to_address" value="eric_morgan@infomotions.com">
<input type="hidden" name="mailer" value="mail.infomotions.com">

<!-- carbon copy and blind carbon copy a couple of addresses -->
<input type="hidden" name="cc" value="ericmorgan@aol.com">
<input type="hidden" name="bcc" value="emorgan@sunsite.berkeley.edu">

<!-- let's create a form requesting more information on predefined topics -->
What is your email address? <input type="text" name="from_address"><br>
What fruit do you want to know more about? 
<select name="subject">
<option value="apples">apples
<option value="oranges">oranges
<option value="cherries">cherries
<option value="pears">pears
</select><br>

<input type="submit" value="submit">

</form>

The last form of this section demonstrates the use of the redirect special variable.

<form action="./email.cgi" method="POST">

<input type="hidden" name="to_address" value="eric_morgan@infomotions.com">
<input type="hidden" name="mailer" value="mail.infomotions.com">

<!-- after processing redirect the user's browser to pre-written page -->
<input type="hidden" name="redirect"<br>
value="http://www.infomotions.com:81/cgi-bin/redirect-page.html">

email address: <input type="text" name="from_address"><br>

<input type="submit" value="submit">

</form>

Template files and more special variables

Through the use of a feature called "template files" and a few more special variables you can customize email.cgi's output. (Remember, email.cgi's default output is intended to be functional, not beautiful.)

There are three types of template files corresponding to the three types of email.cgi output: email, HTML, and error. Associated with these three templates are three more special vaiables: mail_template, html_template, and error_template, used respectively.

The process behind the use of template files is similar for each type:

  1. Create a valid email.cgi form.
  2. Include an input tag with the name of a template file special variable (ie. mail_template, html_template, and/or error_template).
  3. Assign a value to the input tag corresponding to the name of a file in the same folder as email.cgi.
  4. Create a template file with the name of the corresponding input tag and save it in the same folder as email.cgi.
  5. Edit your template file and include the names of desired email.cgi form input tags making sure the names are surrounded by square brackets ([]). These names surrounded by square brackets are called "tokens" and examples include [to_address], [subject], or [your name]. Be forewarned! The tokens, san brackets, must match exactly the names of the input tags. Case matters.

If done correctly, email.cgi will process the content of your forms, read your template file(s), find/replace the names of your input tags in the files with the values supplied in the form, and finally, return the dynamically created output.

Bug alert! If you use multiple-selection scrolling lists or check boxes as your input types, email.cgi will not function 100% correctly with template files. It is not that email.cgi will crash or anything like that. Rather the find/replace routines inside email.cgi do not accomodate the necessity to find/replace multiple-selection items. Consequently, examples like the pizza form above can not be used very well with template files.

Each special variable associated with template files is described below:

  1. mail_template - Use this special variable associated with an existing template file to format the email sent by email.cgi. It allows you to create email.cgi email messages sent to you in such a way that it will be easy for you to process them once recieved. For example, if you administrate a mailing list, then you might be able to create an email.cgi form, have it's output formatted into a mailing list command, and sent to the mailing list server for processing on the end-user's behalf. If you want to import the contents of forms into a database, then the mail_template file may be tab-delimeted for easy processing. Remember, the contents of your email output is not necessarily intended to be read by humans; you can format the output so it can be read by computers. This feature also allows you to selectively add or delete any of the "free environment variables" returned by the default email.cgi message output. An example input tag includes:

    <input type="hidden" name="mail_template" value="problem-report-mail">
  2. html_template - This special variable is associated with the HTML template page returned to the end-user after they submit a form. Through the use of this special variable you can echo the end-user's input in a manner congruant with the style of your site. Here is a sample input tag:

    <input type="hidden" name="html_template" value="problem-report-html">
  3. error_template - Use this special variable and its accociated template file to format any error messages email.cgi may generate. Like the html_template special variable, this special variable's purpose is to allow you to create output that looks like the balance of your HTML pages. An example includes:

    <input type="hidden" name="html_template" value="problem-report-error">

    Remember the following two distinctions concerning the use of this special variable. First, if any email.cgi error occurs and the error_template does not point to a valid error template file, then email.cgi really generated two errors but will report the error_template error before it will report anything else. To minimize this problem, make sure all other errors are resolved before you use this special variable.

    Second, a specific token is used as a placeholder for email.cgi error messages, [email.cgi error message]. Insert this specific token in your error_template file so the error message makes more sense to your end-users.

Finally, here's a hint. Create your form first and get it working before you start adding template files, then add the template files one at a time making sure the error_template file is implemented last. The following form includes these all three of the special variables associated with template files.

<form action="./email.cgi" method="POST">

<input type="hidden" name="to_address" value="eric_morgan@infomotions.com">
<input type="hidden" name="mailer" value="mail.infomotions.com">

<!-- add a human's name, just for fun -->
<input type="hidden" name="support person" value="Eric">

<!-- let's make a problem report; include pointers to three template files -->
<input type="hidden" name="mail_template"  value="problem-report-mail">
<input type="hidden" name="html_template"  value="problem-report-html">
<input type="hidden" name="error_template" value="problem-report-error">

<!-- garner some input, some of it required -->
What is your name? <input type="text" name="user_required_name"><br>
What is your email address? <input type="text" name="from_address"><br>
Select the type of problem:
<select name="subject">
<option value="making money">making money
<option value="saving money">saving money
<option value="spending money">spending money
<option value="none of these">none of these
</select><br>
What's the problem?<br>
<textarea rows="7" cols="30" name="user_required_unwrap_problem"></textarea><br>

<input type="submit" value="submit">

</form>

Here are the corresponding template files. First the very simple mail_template (problem-report-mail):

name: [user_required_name]
email address: [from_address]
subject: [subject]
problem: [user_required_unwrap_problem]

Next, here is the html_template file (problem-report-html):

<html>
<head>
<title>[subject]</title>
</head>
<body>

<h2>Thank you</h2>

<p> Dear [user_required_name], thank you for completing
the problem report. We will look into your problem,
[subject], as you described it below right away: </p>

<blockquote>
[user_required_unwrap_problem]
</blockquote>

<p> If you have any other problems, the please direct
them to <a href="mailto:[to_address]">[support
person]</a>. </p>

<p>
Have a nice day.
</p>

<p>
Signed, The Management
</p>

</body>
</html>

Finally, the error_template (problem-report-error):

<html>
<head>
<title>Oops!</title>
</head>
<body>

<h1>Oops!</h1>

<p>
Oops! Some sort of error occured:
</p>

<blockquote>
[email.cgi error message]
</blockquote>

<p>Maybe you didn't complete all the necessary fields
in the form? Try again, and if the problem persists,
then please report it to The Management. </p>

</body>
</html>

Environment variables

As you may or may not know, Web browsers send tiny bits of information about themselves to remote Web servers and therefore CGI programs. These tiny bits of information are usually called environment variables. Email.cgi gives these environment variables to you for "free" and incorporates them into its default output or by design through the use of template files and tokens. There are 9 such "free environment variables" supported by email.cgi, and they are all described below:

Remember, to incorporate the environment variables in the output(s) of email.cgi you must treat each of them as if they were tokens described in the template files section above. In other words, you must insert the names of the variables in your template files exactly as they are shown above and they must be delimited by square brackets ([]).

The form below and its associated html_template file echos all the environment variables.

<form action="./email.cgi" method="POST">

<input type="hidden" name="to_address" value="eric_morgan@infomotions.com">
<input type="hidden" name="mailer" value="mail.infomotions.com">
<input type="hidden" name="html_template" value="environment-html">

<!-- simply ask for their name and email address -->
What is your name? <input type="text" name="user_required_name"><br />
What is your email address? <input type="text" name="from_address"><br />

<input type="submit" value="submit">

</form>

Here is the template file:

<html>
<head>
<title>
Environment variables
</title>
</head>

<body>

<h2>Environment variables</h2>

<p>
<b>[user_required_name]</b>, the following "free
environment variables" were returned by email.cgi:
</p>

<ol>
<li>client_ip_address - [client_ip_address]</li>
<li>client_name_address - [client_name_address]</li>
<li>client_browser - [client_browser]</li>
<li>user_name - [user_name]</li>
<li>user_info - [user_info]</li>
<li>server_info - [server_info]</li>
<li>server_port - [server_port]</li>
<li>execution_path - [execution_path]</li>
<li>the_referrer - [the_referrer]</li>
</ol>

<p>
Thank you for using email.cgi.
</p>

</body>
</html>

Error messages

There are fourteen errors email.cgi traps. Each is associated with an error message. Some occur because there are missing values for required or end-user required variables. Other errors occur because of invald values for supplied template files. The balance of the error messages you will probably not encounter. If you do, then there is most likely something wrong with your installation or the logic of email.cgi itself. Each of the error messages are described below:

Revision history


Creator: Eric Lease Morgan <eric_morgan@infomotions.com>
Source: This software documentation was never formally published.
Date created: 1994-11-02
Date updated: 2004-12-07
Subject(s): computer programs and scripts; AppleScript; email;
URL: http://infomotions.com/musings/email-cgi/