The Envex Form Mailer is a fully featured form mailer, which is template based, giving you full control over how e-mail messages are formatted. The script works on both, UNIX and Windows web servers. Many features are supported such as:

• Required fields
• Multiple form pages
• Save results to a text file
• Template based, allowing for full customization
• File attachments
• Multiple recipients
• Personlized auto-reply

Installation of the Envex Form Mailer is fairly simple and straight forward. To install the script on your web server, complete the following steps:


1.1 Modify the path to Perl

Open up the formmail.cgi script in a text editor such as Notepad, and make sure the first lines points to the full path to perl on your server. If you are unsure of the path to perl, contact your server administrator.


1.2 Modify the formmail.cgi script

Scroll down below the copyright information, and there are four variables, which you need to set. The below table gives a description of all four variables:

Variable	Description
$mailtype	You can send e-mail through either Sendmail or a SMTP mail server. This variable must be set to either: sendmail smtp If you're using a UNIX / LINUX web server, it's recommended you use Sendmail. Otherwise, if you're using a Windows server, you should use SMTP.
$mailprog	If you're using Sendmail, the full path on your server to sendmail. If you're unsure of this, contact your server administrator. Otherwise, if you're using SMTP, the host name of the SMTP server, such as 'mail.domain.com'
$referer_check	If set to 1, a referer check will take place, and the form must be submitted from your domain. However, people using internet firewall program may receive an error. If you are unsure, leave this at 0.
@referers	Only applicable if $referer_check is set to 1. These are the domain name(s), which the HTML form can be submitted from. If the HTML form is submitted from a domain name not in this list, an error will occur.

1.3 Upload the formmail.cgi script

Login to your web server through FTP, and upload the formmail.cgi script to your /cgi-bin/ directory. Make sure you upload it in ASCII mode! If you're using a UNIX / LINUX web server, CHMOD the formmail.cgi script to 755.



To create your HTML form, you first need a <FORM> tag, pointing to the formmail.cgi script, with a method of POST. It should look something like:

<FORM ACTION="http://www.mydomain.com/cgi-bin/formmail.cgi" method="POST">

If you're using file attachments, you must add enctype="multipart/form-data" to the <FORM> tag, which would then look something like:

<FORM ACTION="http://www.mydomain.com/cgi-bin/formmail.cgi" method="POST" enctype="multipart/form-data">

You can add in any form fields you would like to your HTML form. The below table lists all special and required form fields, supported by the Envex Form Mailer:


Field Name: recipient

The e-mail address, which the e-mail message wlll be sent to. If wanted, this can be a comma delimited list of e-mail addresses, and the message will be sent to each one of them.

Example:

<input type="hidden" name="recipient" value="user@domain.com">
<input type="hidden" name="recipient" value="user@domain.com,user2@somedomain.com">

Field Name: subject

The subject of the e-mail message, which is sent to the recipient.

Example:

<input type="hidden" name="subject" value="New Form Submission">

Field Name: template

The file name of the e-mail message template, which is sent to the recipient. Exactly how to create the template is explained below.

Example:

<input type="hidden" name="template" value="email.msg">

Field Name: from_email

The e-mail address of the person submitting the form. This is normally a text field, and is required if you would like an automated reply sent to the person submitting the form. This will also be displayed as the sender of the e-mail message sent to the recipient.

Example:

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

Field Name: from_name

The name of the person submitting the form. This is normally a text field. This will also be displayed as the sender of the e-mail message sent to the recipient.

Example:

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

Field Name: reply_template

The file name of the e-mail message template, which is sent to the from_email field. This is the automated reply message, sent to the person submitting the form. How to create the template itself is explained below.

Example:

<input type="hidden" name="reply_template" value="reply.msg">

Field Name: reply_subject

The subject of the e-mail message, which is sent to the from_email field. This is the subject sent to the person who submitted the form.

Example:

<input type="hidden" name="reply_subject" value="Thanks for the form">

Field Name: reply_from_email

The e-mail address used as the sender of the e-mail message, sent to the from_email field. This is the e-mail address, which will appear in the From: line of the message sent to the person who submitted the form.

Example:

<input type="hidden" name="reply_from_email" value="support@domain.com">

Field Name: reply_from_name

The name used as the sender of the e-mail message, sent to the from_email field. This is the name, which will appeaer in the From: line of the message sent to the person who submitted the form.

Example:

<input type="hidden" name="reply_from_name" value="Customer Support">

Field Name: results_file

Only required if you would like to save the results of every form, to a text delimited file. This is the filename, which all results will be saved to.

Example:

<input type="hidden" name="results_file" value="results.txt">

Field Name: results_fields

Only required if you're saving results to a text delimited file. This is a comma delimited list of form fields to save.

Example:

<input type="hidden" name="results_fields" value="from_name,from_email">
<input type="hidden" name="results_fields" value="ip_address,field1,field2,from_name,from_email">

Field Name: results_delim

The delimiter used to save the results to a text file. If this is not specified, all results will be tab delimited.

Example:

<input type="hidden" name="results_delim" value="::">

Field Name: next_template

Used for multiple form pages, or if you would like to print out a specific 'thank you' web page after someone submits the form, personalized with what the person submitted. This is the file name of the web page to print out, once the form has been successfully submitted.

Example:

<input type="hidden" name="next_template" value="form2.html">

Field Name: redirect

The URL to redirect the user to, after they've submitted the form.

Example:

<input type="hidden" name="redirect" value="http://www.domain.com/thankyou.html">

Field Name: req-*

You can easily make any form fields required, by simply placing req- in front of the field name. If the field is left blank, an error message will be given off.

Example:

<input type="text" name="req-field1">
<input type="text" name="req-anotherfield">

Field Name: file_admin-*

You can have file attachments sent to the recipient, by simply placing file_admin- in front of the form field name. The script will automatically take the contents of the file, and add it as an attachment to the e-mail message, sent to the recipient.

Example:

<input type="file" name="file_admin-field1">
<input type="file" name="file_admin-anotherfield">

Field Name: file_user-*

You can have file attachements send the from_email field, the person who submitted the form, by simply placing file_user- at the beginning of the form field name. The script will automatically take the contents of the file, and attach it to the e-mail message, sent to the from_email field.

Example:

<input type="file" name="file_user-field1">
<input type="file" name="file_user-anotherfield">

Other than that, you can create your HTML form any way you wish. Simply add any other form fields you would like to your form.



As stated above, you can use the template and reply_template form fields to specify the filename of the e-mail message templates. All templates must be uploaded in the same directory as the formmail.cgi script. To create a message template, simply open up a text editor such as Notepad, and write any message you would like.

You can personalize your e-mail message with the contents of the HTML form by placing ~ marks around the names of form fields. For example, if you have a field in your HTML form like:

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

You would simply need to place ~address~ anywhere in your e-mail message, and it would be replaced with the contents of the "address' form field. There are a couple other fields supported, which are:

Field	Description
~date_submitted~	The exact date and time the form was submitted
~ip_address~	The IP address of the person who submitted the form
~remote_host~	The remote host of the person who submitted the form. Please note, depending on your server's configuration, there's a good chance this will always be blank.

Then just save the message as a text file, using the filename you specified in the template or reply_template field, and upload it to your web server, in the same directory as the formmail.cgi script.



You can use multiple form pages, by using the next_template form field as explained above. Your first HTML form is hosted on your web site as normal, and all other HTML forms must be uploaded to the same directory as the formmail.cgi script. You need to create all HTML forms exactly as stated above. The only difference is you need to carry the form values from one form, over to the other. This can easily be done through hidden form fields.

For example, if you have the form fields from_name, from_email, and address on your first HTML form, you would place the following hidden form fields in your second HTML form:

<input type="hidden" name="from_name" value="~from_name~">
<input type="hidden" name="from_email" value="~from_email~">
<input type="hidden" name="address" value="~address~">

Then, use the next_template form field to print out the second HTML form. When the second form is displayed, the values of the hidden form fields will be replaced with the contents of the fields, filled out on the previous form. You can have e-mail messages sent out after any HTML form is submitted. The script simply looks for the template and reply_template form fields. If either are found, the needed e-mail messages will be sent out.