****************************
CGIMail V2.0 07/14/98
Copyright 1998 NSI WEB Design
Http://www.nsiweb.com/cgisoftware/cgimail
E-Mail: support@nsiweb.com
****************************


What is CGIMail?
----------------

CGIMail is a web form remailer for Windows 95/NT Web Servers.
This CGI executable allows you to send information gathered
from a form in a hypertext document to an e-mail address in an
easily readable and customizable format. CGIMail will only work
for the domain it was registered for (multiple domains may be
added by contacting NSI WEB ).


Prerequisite
-----------

1)In order to run CGIMail, a Windows 95 or NT Web server capable of running CGI programs is needed.

CGIMail has been tested on the following Web servers:

O'Reilly Website and Website Pro
Microsoft Internet Information Server 1.0
Microsoft Internet Information Server 2.0
Microsoft Internet Information Server 3.0
Microsoft Internet Information Server 4.0 ***Setup instructions for 4.0 is different please refer to the last page**
Microsoft Personal Web Server 4.0
Netscape Enterprise Server
Purveryor

Note: CGIMail should work on all other windows based web servers that support CGI programs, though this program is not guaranteed to work on them.

2)CGIMail also requires a mail server compatible with the SMTP protocol in order to deliver mail.

CGIMail has been tested on the following Mail servers:

Netscape Mail Server
Post.Office
SLMail/NT
SLMail 95
Unix sendmail
Unix qmail


Note: If you can't run CGIMail from your server because of any 
reason whatsoever, you can rent a copy of CGIMail which will be placed 
in our servers.  This will work in the same manner as if you owned
the package yourself, however, no installation is required. All
you have to do is add a few html tags to your web page and you
are done!
There is an annual fee of $50.00 for this service.


What is new in this version
-----------------------------
Version 2.0 of CGIMail is a totally new compilation of the product. Therefore, forms used with older versions of the product need some modifications in order to work with this current version. New features in this version are:
-Customizable error message for each user defined form input.
-Support for a secondary mail server.
-Customized field ordering and required fields now work together.
-Support for local usage of the program.
-Support for PGP encryption plug in, and MIME attachments plug in (see MODULES below)
-No limit on lengths of fields or amount of inputs.
-Detailed log error files.
-Compatibly with CGI-Bin.
-Instant movement to returntourl field.


Installing CGI Mail
-------------------
Run the install program from the Web Server. CGIMail will install
the necessary files needed to run the program on your server.
When prompted to enter the path of your CGI directory,
make sure the path you choose is capable of executing
windows based CGI programs. If you receive a "Cannot register cimail.ocx" 
error then you must update your copy of Windows 95 or NT to accept active x dll's.
There are two methods to do this, one is to install Internet Explorer
3.01 on your computer.  The second method is to download
axredist.exe from Microsoft.  It is fairly large (about 10.3 Meg), but the
only file you need is called axdist.exe (about 400K).  Either of these
methods will achieve the same thing - updating your .dll's to a newer
version capable of accepting active x controls.

The files that will be extracted are cgimail.exe, sendmsg.exe and sendmsg.ini. The sendmsg.ini file tells CGIMail where to find sendmsg.exe. By default, sendmsg.ini contains the text "sendmsg.exe" which tells CGIMail that sendmsg.exe is located in the same directory as itself. The program will function fine this way, expect for few second lag time between the user submitting the form and seeing the return URL appearing. In order to eliminate this lag time, place sendmsg.exe in a non-cgi directory (i.e. c:\cgimail). Then edit sendmsg.ini so it points to the correct location of sendmsg.exe
Example:

sendmsg.exe is placed in c:\internet\cgimail

sendmsg.ini looks like this: c:\internet\cgimail\sendmsg.exe

If there are any errors or the path entered in sendmsg.ini doesn't exist, the mail will not be sent.


REQUIRED FIELDS
---------------
There are 8 required fields needed in order for CGIMail to work properly. 

1) Form definition

This html tag tells the page where to find CGIMail.
eg.
<FORM METHOD="POST" ACTION="http://www.abc.com/cgi-bin/cgimail.exe">

METHOD must be the same as shown above, the ACTION must be changed to point where CgGIMail is located and can be accessed by the Internet.

2) email field

This field must be included. It defines the "From: " part of the E-mail message and can be set to anything. A good example would be forminput@yourdomain.com. This field can also be set by the user on the page (A good idea if you want to be able to respond to the form E-mail). Though, this field is required for the mail to be sent properly. If making it visible to users, set it to REQ_email (see REQ_ prefix bellow) in order to force the user to fill it out.
eg.
<Input type="text" name="email"> (visible)
<Input type="hidden" name="email" value="forminput@yourdomain.com"> (hidden)

note: if an e-mail address with incorrect e-mail syntax (eg. bob@bob) is entered, an error message will appear after the submit button is hit.

3) smtpserv field

This field sets the SMTP server (mail server). It is required for the mail to be sent. If an invalid SMTP server is entered, an error file will be generated in the same directory as sendmsg.exe called "mailerr.txt". If you are unsure of your SMTP server, ask your network administrator.
eg.
<input type="hidden" name="smtpserv" value="mail.gte.net">

A second smtp server can be specified (incase there is an error with the first server) by placing a $ and the second server in the value field.
eg.
<input type="hidden" name="smtpserv" value="mail1.gte.net$mail2.gte.net">

4) mailto field

This fields tells CGIMail where to send the mail it generates.
eg. <input type="hidden" name="mailto" value="youremail@yourcompany.com">

5) subject field

This field sets the subject of the message
eg. <input type="hidden" name="subject" value="subject of message here">

6) returntourl field

This fields specifies the homepage that the user will be taken to 
after filling out the form. If the location of the target homepage is
in a different domain, then the "http://" syntax has to be used.
eg. <input type="hidden" name="returntourl"  value="http://www.yourdomain.com/thanks.html">


OPTIONAL FIELDS
---------------
These fields are optional and help to control the final look of
the email sent to you.  You can see some of these at our "advanced"
cgimail form -
http://www.nsiweb.com/cgisoftware/cgimail/test-advanced.html

1) header#
eg. <input type=hidden name="header01" value="BILL TO INFO">

The header field tells CGIMail to insert text into the final e-mail.
This text can be anything and is usually used for descriptive
purposes. NOTE: the header must have a unique number at the end
(header02, header03...). Can be used as footers as well.

2) hidden#
eg.  <input type="checkbox" name="hidden01" value="Product info">

The hidden field displays the value in the e-mail, by itself
indented five spaces.  This is useful when the user has a large
amount of data that can be checked off, but only wants the checked
data to be displayed in the e-mail, and not the name of the field.
NOTE: the hidden must have a unique number at the end (hidden02,
hidden03...).

3) blank#
eg. <input type=hidden name="blank01" value="1">

The blank field is used to insert a blank line in the
e-mail. NOTE: the blank must
have a unique number at the end (blank02, blank03...).
Set the value to "1".

4) REQ_<fieldname>
eg. <Input type="text" name="REQ_Address">

To designate a field as required, making it impossible to
submit a form without having this field filled out, put a
"REQ_" before the field name. 

5) ERR_<fieldname>
eg. <input type="hidden" name="ERR_Address" value="<center>You MUST fill out the address field!</center>">

This sets the error message to be displayed if a user does not enter something in a REQ_'d field. the names of the fields have to match up EXACTLY for this to work. (REQ_Address and ERR_Address, REQ_name and ERR_name). If a field has REQ_ before it, and no associated ERR_ field, the following error will be displayed:
"<name of field> is a required field! please go back to the Referring Document and enter the information we need to process your form."
where Referring Document is a link to the page the user just came from.
Note: HTML tags can be used with ERR_

6) cc
eg. <Input type="hidden" name="cc"
      value="webmaster@mydomain.com,info@mydomain.com">

Sends carbon copies of the email, also can be used in conjunction with a
radio button box to send to several different groups of people.  Make sure
each name is separated by commas and NO SPACES.  Also - the email
addresses must be valid.

7) bc
eg. <Input type="hidden" name="bc"
      value="webmaster@mydomain.com,info@mydomain.com">

Sends blank copies of the email, also can be used in conjunction with a
radio button box to send to several different groups of people.  Make sure
each name is separated by commas and NO SPACES.  Also - the email
addresses must be valid.

8) nsfields
eg. <Input type="hidden" name="nsfields" value="5">

This field specifies the total number of fields when using customizable 
field ordering.  For more information see "CUSTOMIZABLE FIELD ORDERING"
below.


KEYWORDS
-------
There are a few characters and words that cannot be part of your field values. If these keywords are present in the values, CGIMail might not work properly. These keywords are: the "|" character, and the word "file" only if the MIME MODULE is installed.



CUSTOMIZABLE FIELD ORDERING
---------------------------

Note: Although this is an optional feature for most users, users
of Netscape's newer web servers must use Customizable Field Ordering
to avoid Netscape's arbitrary ordering of form fields when sent through email.

Some times the order in which fields are presented in the web page
is not necessarily the best order for the individual who actually
manages the administration of all user input. For example, if the
information returned by CGIMail is later going to be redirected to
a database, the individual who is reading the messages and entering
the information in the database might be better served if the order
of the fields as shown in the email message match the order in which
they will be entered in the database.

To use customizable field ordering, the "nsfields" field must be present 
in the web page.  In addition to this, a special naming convention has 
to be used as well. This convention mandates that the names for user input 
fields begin with a three digit number describing the order in which these
fields will appear in the email message. 
So for example, if the first field in the email message
will be the credit card number, the name for this field in the html code
has to be of the form "000creditcardnumber",where "000" tells CGIMail 
this will be the first field in the email message.  If the second field
in the email message will be the email address of the user, then the name
for that field in the html code has to be of the form "001email", and so
on.  Please note that the number HAS to be a three digit number and the
numbering has to begin with "000" . For this example, the "nsfields" field
has to have a value equal to the total number of user input fields, and
the "emailnum" field has to have "001" as its value. Refer to the 
following example for any doubts.

<FORM action="../cgi-win/cgimail.exe" method="post">
<INPUT type="hidden" name="smtpserv" value="mail.nsiweb.com">
<INPUT type="hidden" name="mailto"   value="alexf@nsiweb.com">
<INPUT type="hidden" name="subject"  value="Online Form">
<INPUT type="hidden" name="returntourl" value="http://localhost">
<INPUT type="hidden" name="nsfields" value="8">
Name:
<INPUT type=text size=30 maxlength=256 name="005Name"><br>
E-Mail:
<INPUT type=text size=20 maxlength=256 name="006email"><br>
Address:
<INPUT type=text size=20 maxlength=256 name="008Address"><br>
City:
<INPUT type=text size=20 maxlength=256 name="001City"><br>
State:
<INPUT type=text size=2 maxlength=256 name="002State"><br>
Zip:
<INPUT type=text size=10 maxlength=256 name="003Zip"><br>
Comments:
<TEXTAREA name="004Comments" rows=2 cols=30></TEXTAREA><br>
<INPUT type=submit><INPUT type=reset name="reset" 	value="reset">
</FORM>

The example above will produce a web page with the fields
organized in the same order as shown; however, the email
message created by CGIMail will be organized in the order
indicated by the prefixes in the names of the fields. In this 
case it will be: Address, City, State, Zip, Comments, Name,
and email. 

Note: If the nsfields is not entered properly, or not all user inputs start with a number as above, one of two errors will be outputed:
An internal error has occured!: Type Mismatch
An internal error has occured!: Subscript out of range

Please review your form if you experience these errors.

THE FORM
--------                                                 
CGIMail is used to send information in a form to an
email address. The information gathered by the form can
range from the simple, to the diverse. You can gather
simple name and address information with text boxes. 
	
CGIMail supports many basic input types. These include
text, radio buttons, checkboxes, and pulldown menus. By
using the optional fields listed above, all of these input
types can be incorporated into a logical gathering of
information. Furthermore, CGIMail can also be configured 
to handle file uploads and encryption of the form data, 
refer to MODULES below. For working examples of our form, visit:
http://www.nsiweb.com/cgisoftware/cgimail/test-simple.html
and
http://www.nsiweb.com/cgisoftware/cgimail/test-advanced.html
or view the example below.


MODULES
-------

This version of CGIMail is configured to handle 2 drop in modules.

1) File Uploading / MIME MODULE

This MODULE allows the usage of a new HTML input type called FILE. This allows people to upload files via web pages. CGIMail's MIME Module will take the uploaded file, and send it along with the form data as a MIME attachment. The file can then be manipulated via a mail client. 
eg. Bob is running a contest on the web to find the cutest baby. People visit his page and upload their baby pictures. Bob receives his normal CGIMail form data, along with the included picture in his mail box. Bob views the pictures and finds a winner. 
The HTML: 
Upload the babies here! <INPUT TYPE=FILE NAME="file1"><p>
After the MIME module is purchased, the only thing that has to be done 
is drop the file into the cgi-bin directory, and add the html tag.

2) Encryption of form data.

This MODULE converts the form data into an PGP encrypted message that can only be visible to the person that's key was used to encrypt the data. An input type (pgpkeyid) sets the data encryption key. When the data arrives in mailboxes, the decryption takes place by entering the secret key, and the data is viewable. This MODULE makes use of the highest level of encryption available today.

For more information about these modules, please visit http://www.nsiweb.com/cgisoftware/cgimail.


Example Form
------------

This simple form demonstrates how to send a simple form output with CGIMail:

<HTML>
<HEAD>
<TITLE> TEST PAGE </TITLE>
</HEAD>
<BODY>
Please, enter your personal information:<P>
<FORM ENCTYPE="multipart/form-data" FORM METHOD="POST" ACTION="http://localhost/scripts/cgimail.exe">
<BR>
<input type="hidden" name="header1" value="This E-mail was sent via CGIMail">
<input type="hidden" name="blank1" value="1">
<input type="hidden" name="header2" value="Please process the data ASAP">
<input type="hidden" name="email" value="form@test.com">
<input type="hidden" name="mailto" value="admin@test.com">
<input type="hidden" name="smtpserv" value="mail1.test.com">
<input type="hidden" name="subject" value="Test Form">
<input type="hidden" name="returntourl" value="http://www.test.com/thankyou.html">
First Name: <INPUT TYPE="text" NAME="REQ_FirstName">
Last Name: <INPUT TYPE="text" NAME="REQ_LastName">
Age: <INPUT TYPE="text" NAME="Age" SIZE=5 >
<input type="hidden" name="ERR_FirstName" value="<center><h1>You Must enter your first name!</center></h1>">
<input type="hidden" name="ERR_LastName" value="<h5>So now you have no last name huh?</h5><br>">
<INPUT TYPE="reset"> 
<INPUT TYPE="submit"  VALUE="send the info!">
</BODY>
</HTML>

***Installing CGI Mail 2.5 on Microsoft Internet Information Server 4.0***
   ---------------------------------------------------------------------

The installation setup for Microsoft Internet Information Server 4.0 is the same as other servers except; CGIMail cannot be installed in the cgi-bin directory or the script directory. CGIMail has to be placed in a separate directory and the web sharing properties in the new directory has to be set; the execute option has to be enabled.

In windows explorer go to the folder that contains CGIMail. Go to the properties of the folder and then select the web-sharing tab. In the properties of the alias directory you created, select execute as one of the attributes.






_________________________________

For further information you can get in touch with NSI WEB at
516-847-0201 from 9:30AM to 6:00PM Monday through Friday EST
or email us at support@nsiweb.com.

Thank you for purchasing CGIMail, please check the NSI WEB Mall
periodically for further updates and new products at
http://www.nsiweb.com.

-NSI WEB Programming Team.
