The MailPost^™ user's guide

This guide will help you write a WWW form that sends an e-mail message to you. The following steps are required:

1. Create an e-mail template.
2. Create the HTML form.
3. Make sure the ACTION is correct.
4. Test your MailPost form
5. Create more advanced HTML forms.
6. Go live with MailPost.

The following steps are optional.

• Add text to the success page.
• Use an alternate success page.
• Make some inputs required.
• Use an alternate error page.
• Accessing CGI environment variables
• Placing the Date & Time in an email message
• Using the Auto-Reply feature

• Special form variables
• Special template variables

Create an e-mail template.

Before you start receiving e-mail messages through the web, you should decide what these messages should look like. Create an ASCII file, called an e-mail template, that looks something like this:

To: me@mydomain.com                               HEADER LINES
Subject: Questionnairre
                                                  blank line
What is your name?      [yourname]                BODY
What is your address?  [address]
What is your zip code?  [zipcode]

The template file will be used by the MailPost program, so before you upload the file to your WWW server, be careful to follow these guidelines:

1. Wherever you want the user of your form to supply information, use a word or phrase inside square brackets, e.g. Your name: [yourname]. .
2. Make sure the address in the To: field is correct.
3. If there are blank lines among the header lines, remove them.
4. If there are blank lines before the header lines, remove them.
5. Make sure all your header lines are valid. The first character on the line must be a letter. Most information should go in the message body; don't make up your own headers.
6. Make sure there is a blank line between the header lines and the body.
7. Make sure you save it as ASCII text. For example, if you are using Microsoft Word, use "Save As" and choose "Text Only with Line Breaks."
8. If you created the file on a computer other than a PC, be sure to upload it as text, i.e. CR's translated to PC format. (If you don't, your file might look like one long line to MailPost.)

Now go ahead and upload your e-mail template to the WWW server and look at it with your WWW browser.

Create the HTML form.

Usually, when you create an HTML form, you need to give people a way to supply an email address. Now you need to add a line to the top of your email template like this:

From: [email]

So now the template file looks like:

To: me@mydomain.com
From: [email] 
Subject: Questionnairre
                                   
What is your name?      [yourname] 
What is your email address?     [email]      
What is your address?  [address]
What is your zipcode?  [zipcode]

Make sure the ACTION is correct.

The trickiest part of the HTML form is getting the ACTION of your HTML form set correctly. There are two parts to the ACTION URL.

http://www.mydomain.com/cgi-location/MailPost.exe/mydirectory/template.txt
\                                               /\                         /
 `---------------- Part 1 ---------------------'  ` ------ Part 2 --------'

Part 1

Place the full domain name and path to MailPost, which will be located in the appropriate cgi-location directory of the webserver (ie for WebSite, Standard CGIs go into cgi-shl. Win-CGIs go into cgi-win).

Part 2

Place the path to your email template after MailPost.exe. In this example, the user has a directory name "mydirectory" and the template file "template.txt" resides in this directory.

For our example, the HTML code would look like this:

<FORM METHOD="POST"
 ACTION="http://www.mydomain.com/cgi-directory/MailPost.exe/mydirectory/template.txt">
<P>Your e-mail address: <INPUT NAME="email"></P>
<P>Your name: <INPUT NAME="yourname"></P>
<P>Your address: <INPUT NAME="address"></P>
<P>Your zipcode: <INPUT NAME="zipcode"></P>
<P><INPUT TYPE="submit" value="Send e-mail"></P>
</FORM>

This is a very simple example. Note that the NAME of each input corresponds to what you previously put in the email template. In this example they are email, yourname, address, and zipcode. This is the key concept in using MailPost. Be careful to make them exactly the same; if you put NAME="yourname" in your HTML form and [name] in your email template, the input will not show up in the email.

Test your MailPost form

You can test your MailPost form without sending an email message by including the hidden variable named *nosend* in your HTML form:

<INPUT TYPE="HIDDEN" NAME="*nosend*">

MailPost will return a sample of what your email message will look like. If all looks good, you can then go "live" by removing the *nosend* variable in your HTML form.

Create more advanced HTML forms.

To learn to create more complicated forms, read NCSA's guide. All of their example forms can be converted to MailPost forms merely by changing the ACTION. Unlike other forms-to-email programs, you are not required to use hidden inputs with special names.

All types of inputs (radio buttons, etc.) work the same way. Each input needs a unique NAME, and that name must appear within square brackets in your email template. It's that simple.

Go live with MailPost.

Once you've set the ACTION correctly in your HTML form (and you've removed the *nosend* input variable if you used it), try it out! You should receive an email message with the processed form. If not, go back and make sure you correctly followed the instructions on this page.

If it works, you've successfully mastered the fundamentals of MailPost. Congratulations!

Optional: Add text to the success page.

When mail is sent, a page appears with the text of the email message. You may use a hidden variable in your HTML form called addendum to add your own text. Here is a simple example:

<INPUT TYPE="hidden" NAME="addendum" VALUE="Thank you!">

You may also place HTML codes in the addendum variable as well, although they may or may not be supported by your user's browser.

Optional: Use an alternate success page.

If you don't like the default page that comes up when email is successfully sent, you can specify an alternate URL using a hidden variable called success in your HTML form, e.g.

<INPUT TYPE="hidden" NAME="success" VALUE="http://www.mydomain.com/thanks.html">

Note: You MUST use the full http: path, not relative paths to the document.

There is no way to make this alternate success page contain information the user submitted in the form.

Optional: Make some inputs required.

If you would like to automatically reject forms with certain inputs left blank, add the prefix required- to the name of the input in both your HTML form and your email template. Here is an example:

In the HTML form:

Your email address: <INPUT NAME="required-email">

In the email template

Your email:      [required-email]

Optional: Use an alternate error page.

If you don't like the default page that comes up when a required field is left blank, you can specify an alternate URL using a hidden variable called *on-error* in your HTML form, e.g.

<INPUT TYPE="hidden" NAME="*on-error*" VALUE="http://www.mydomain.com/error.html">

Note: You MUST use the full http: path, not relative paths to the document.

Optional: Accessing CGI environment variables

MailPost allows you to embed CGI environment variables into your template file by simply prefacing the CGI environment name with a dollar sign "$". For example:

         [$HTTP_REFERER]

will put the referring URL into the email message. All CGI environment variables are uppercase.

Optional: Placing the Date & Time in an email message

You can insert the Date & Time into your email message by inserting the special template variable *date-time* into your template file.

    From: mailpost@mcenter.com
    To: mailpost@mcenter.com
    Subject: Date & Time variable

    This message was generated at: [*date-time*]

This variable is not for use in the header of the template file, only the body of the template file. The *date-time* variable uses your system's "short" date & time settings under Control Panel | Regional Settings

Using the Auto Reply feature

Beginning with version v3.04, MailPost can create and send an automatic reply message. MailPost allows you to send a generic or a customized Auto Reply message. The customized Auto Reply message is created using a template file, just as you do for your form. All variables that are available to your form's template file are available to the Auto Reply template. The Auto Reply feature is enabled by adding a line in the header section of your form's template file.

To use the Auto Reply feature, follow these steps:

In the template file for your form, insert the "X-AutoReply:" header, as in:

From: mailpost@mcenter.com
To: you@there.com
Subject: Information
X-AutoReply:

  Thanks for visiting our website.  etc., etc..

If you do not specify a template file to use for the Auto Reply message, MailPost will create a generic message and email it. If you do specify an Auto Reply template file, MailPost will use that template file to format your Auto Reply message.
Note: The Auto Reply's template file must reside in the same directory as the template file used for the form. If it is not found, MailPost will generate its' generic Auto Reply message.

If you wanted to create a custom Auto Reply message using a reply template file named "form-reply.txt", the form's template file would be:

From: mailpost@mcenter.com
To: you@there.com
Subject: Information
X-AutoReply: form-reply.txt

Remember that your Auto Reply template takes on the same structure as a regular form template. You include the To:, From: and Subject: headers, separate the headers and body with a blank line, which is followed by the body of the message. All variable substitutions will take place, just as it did in the form's template file.

Special form variables

required-xxxxxx

The HTML code: <INPUT NAME="required-email" VALUE=""> requires the user to enter data for the "email" variable

*nosend*

The HTML code: <INPUT NAME="*nosend*" VALUE=""> lets the user see their message, but it will not be emailed. This is useful for testing purposes. This is usually a HIDDEN form variable.

*debug*

The HTML code: <INPUT NAME="*debug*" VALUE=""> would append certain MailPost variables to the MailPost results page. This is usually a HIDDEN form variable.

*on-error*

The HTML code: <INPUT NAME="*on-error*" VALUE="http://www.mydomain.com/error.html"> sends the user to the page specified if any required fields were missing. Note: You MUST use the full http: path, not relative paths to the document. This is usually a HIDDEN form variable.

append

The HTML code <INPUT NAME="append" VALUE="Thanks for dropping by"> would add the line: Thanks for dropping by at the end of the MailPost Result page. You can also embed HTML code in the append value tag, such as VALUE="<P>Go back to <A HREF="http://www.mydomain.com/">our homepage</A></P>" This is usually a HIDDEN form variable.

success

The HTML code <INPUT NAME="success" VALUE="http://www.mydomain.com/thanks.html"> would redirect the user to the page that is located at: http://www.mydomain.com/thanks.html instead of displaying the normal MailPost Results page. Note: You MUST use the full http: path, not relative paths to the document. This is usually a HIDDEN form variable.

*wrap-text*

The HTML code: <INPUT TYPE="HIDDEN" NAME="*wrap-text*" VALUE="72"> would wrap your email message to 72 characters. This wrapping is only applied to the body of the email message, not to the headers. This is an optional tag, and is only used if you need to force line wrapping for your clients.. This is usually a HIDDEN form variable.

xxxxx.dflt

This extension is used to specify a default value of an HTML form variable. For example, if you had a checkbox named Order in your form. If the checkbox is not checked, the variable's name will appear in the email message, like [Order]. If you specified a default value for Order by using the .dflt extension, you can specify what will appear in the email message if the checkbox is not checked. In the HTML code of the form's section, you would include a hidden variable named Order.dflt and specify the value, such as: <INPUT TYPE="HIDDEN" NAME="Order.dflt" VALUE="no"> This would cause no to appear in your email message where the variable "Order" was if the checkbox was not checked. Note that .dflt must be in lowercase, and as usual, all variable names are case sensitive, so "Order" is not the same as "ORDER".

xxxxx.URLencode

Form variable name extension used to tell MailPost that this variable must be encoded for URL passing. This extension is used primarily when using the *redirect* feature to interact with other CGI programs, such as creating a generic search form. In order to pas the search data back to the search engine, the data must be URL encoded first. If your form had a variable named SearchString that held the data that was being searched for, the form would have a hidden variable: <INPUT TYPE="HIDDEN" VALUE="SearchString.URLencode">

form.xxxxx

Form variable name extension used for value replacement. This extension allows you to assign the value of one variable to another variable. If the HTML form had two variables, one named "A" and one named "B", and the form had the HIDDEN variable: <INPUT TYPE="HIDDEN" VALUE="form.B"> when the form is processed, variable B's value will be given to A, as long as variable B is passed to MailPost. For example, if variable B was assigned to an unchecked checkbox, then variable B would not be passed to MailPost, and no value substitution would occur.

xxxxx.email

Form variable name extension used to check formatting. This extension allows you to check if a form variable is formatted as an internet email address. If the value is not a valid format, MailPost will return an error. <INPUT TYPE="HIDDEN" VALUE="required-your-email.email">

*unique*

Used as a form variable's VALUE. When used, MailPost generates an 8 character "word" which is based on the date and time (down to 1 second intervals). If you have more than one *unique* VALUE setting in your form, they will all be the same value. <INPUT TYPE="HIDDEN" NAME="invoice#" VALUE="*unique*">

|CRLF|

When used, |CRLF| will insert a carriage return and line feed into the text. This is primarily used to help formatting multi-select listboxes. If you have a multi-select listbox, by placing |CRLF| at the end of each option's VALUE, the selected items will be separated by a CRLF in the message.
<SELECT NAME="Items" SIZE="2">
<OPTION VALUE="Item 1|CRLF|" SELECTED="SELECTED">First Item</OPTION>
<OPTION VALUE="Item 2 |CRLF|">Second Item</OPTION>
</SELECT>

Template special variables

MailPost Homepage | Help Index

For additional information not presented here, email mailpost@mcenter.com

For problems concerning this site, email webmaster@mcenter.com