MailForm v1.91
(c) Copyright 1999 Jonathan Potter
Left Side Software

This software requires Windows 95 or Windows NT 4.0 or later to run.

------------------------------------------------------------------------------
This program is distributed under the Shareware concept. If you like and use
this program, please consider registering to support the further development
of this and other great software. You will be given priority when asking for
technical support, and also receive notification of new releases of this and
other software.

Please see http://www.lss.com.au for information on registration.
------------------------------------------------------------------------------

* Note: There is an HTML version of these instructions online at
  http://www.lss.com.au/lss/windows/mf/mf_ins.htm - this version is more
  detailed and also easier to read.


1. Introduction

MailForm is an easy-to-use CGI program for Windows (Win32 only) that sends the results
of a submitted form as an email message. It is primarily designed for use with an
online registration form (and includes the ability to verify that a credit card is
a valid number), but can be used for any form. MailForm requires that there be a SMTP
mail server accessible from the web server machine.

Please note that while the instructions given below are for those using Microsoft
FrontPage, FrontPage is _not needed_, and MailForm can be easily used by anyone.


2. Installing MailForm

Installing MailForm is simple provided you know your way around your web server;
the instructions given here are for Microsoft's Peer Web Services (IIS-jnr) and
assume you will be creating the form with Microsoft FrontPage, however the process
is very similar on other systems.

The MailForm executable (mailform.exe) must be copied into the cgi-bin directory
for your web server. In the default PWS setup, this directory is

	c:\INetPub\wwwroot\cgi-bin

The location may be different on your system, however. This is the only step needed
on the server side to install MailForm. If you are using FrontPage, it should
automatically notice a new addition to your cgi-bin directory (if not, just
Recalculate Links and it should appear in the tree on the left of the FrontPage
Explorer window).


3. Using MailForm

MailForm does not have a WebBot interface, so you can't configure it with a GUI
of its own. However, it is very easy to set up and can be configured through the
FrontPage interface. If you are using another HTML editor, or are creating the
pages by hand, then the procedure will not be exactly the same as that described
below.

Assuming you already have a form created, the first step is to assign MailForm as
the Handler for your form. To do this, right-click on the form and select 
Form Properties... to bring up the Form Properties dialog. Set the Handler type
to "Custom ISAPI, NSAPI, or CGI Script", and then click the Settings button.
The Settings for Custom Form Handler should be configured as follows:

	       Action:	http://www.company.com/cgi-bin/mailform.exe
	       Method:	POST
	Encoding type:

You must give the complete URL for the mailform.exe in the Action field. Click OK
when you have configured the Settings.


4. Configuring MailForm

Each form that uses MailForm can have its own configuration. MailForm is
controlled by the use of Hidden fields within the form. These are fields that
have a name and a value like any other, but are not displayed on the page.
In FrontPage, you add Hidden fields to a form in the Form Properties dialog.
Click Add to add each field, one at a time.

All MailForm configuration fields begin with an underscore character, a
number, and then another underscore (eg _1_). This identifies them as a MailForm
field, and the number is a code used to identify the particular type of field.

Currently there are five different type of MailForm fields:

	_1_	System field
	_2_	Ignore field
	_3_	Credit card number field
	_4_	Required field
	_5_	Email field

The System fields are as follows:

	Name			 Value

	_1_MailTo		 The address to email the results to (eg fred@company.com)
	_1_MailServer		 The address of the SMTP mail server (eg mail.company.com)
	_1_MailSubject		 The subject line of the email
	_1_MailFrom		 The address email is to "come from" (can be any valid address)
	_1_CCMailFrom            The email is also sent to the address in the _1_MailFrom field
	_1_SuccessDocument	 URL to return if the operation succeeds
	_1_FailureDocument	 URL to return if the operation fails
	_1_InvalidCardDocument	 URL to return for an invalid credit card number
	_1_RequiredFieldDocument URL to return if a required field is missing
	_1_CardNotAcceptedDocument
				 URL to return for a credit card that's not accepted
	_1_InvalidEmailDocument	 URL to return for an invalid email address
	_1_NoHotmailDocument	 URL to return for a "hotmail" email address
	_1_BadRefererDocument    URL to return when the form is "referred" by an invalid host
	_1_SortFields		 Set this field to cause fields to be sorted in the email
	_1_TextLog               Set this to log all form submissions to a text file
	_1_HTMLLog               Set this to log all form submissions to an HTML file
	_1_CommaDelimitedLog     Set this to log all form submissions to a comma-delimited text file
	_1_StripEmptyFields	 Set this to cause empty fields to be removed
	_1_AcceptedCards	 Set this to specify the credit cards accepted
	_1_NoHotmail		 Set this to reject "hotmail" addresses
	_1_MailTemplate          Specifies a template to generate the message with
	_1_INIFile               Specifies an alternative ini file to use
	_1_MailIntro             Sets the email introduction line (header)
	_1_AcceptEmptyCardField  Will accept an empty _3_ field as valid
	_1_ConditionalSuccessDocument
	                         Conditionally redirect to a different document on success

The _1_MailTo address is the actual address the email will go to, and so must be valid.
Likewise, _1_MailServer is the address of the SMTP mail server and must also be valid.
_1_MailFrom and _1_MailSubject are not required, but you may like to set these for your
own convenience.

_1_MailFrom lets you set the 'From' address of the email. If _1_MailFrom is set, it must be
either a valid address (contain exactly one @ character), or it must be the name of another
field in the form. This second way lets you take the contents of another field and use it
as the 'from' address for the email (eg, if you have a field where the user enters their
email address, you would give the name of this field as the value of the _1_MailFrom field).

Since v1.4 of MailForm, the _1_MailTo field can contain multiple email addresses, each
separated by commas. The contents of the mail will be sent to each of the addresses in
turn. Also since 1.4, you can have multiple _1_MailTo fields on the one form. This
lets you, for instance, have one hard-coded email address and a user-editable email
address on the same form.

The documents Success, Failure, InvalidCard, RequiredField, InvalidEmail, CardNotAccepted and
NoHotmail are the URLs of documents returned depending on the success or failure of the form
submission. If they are not supplied, a brief default message is given to the user.

The _1_SortFields field causes the field values in the email to be sorted by name (that
is, the field name, NOT the value of the field). The value of the _1_SortFields field
should be set to 1 if you want the fields to be sorted in alphabetical order, or 2 if
you want the fields sorted in numerical order. The _x_ header of field names is
ignored when sorting. If you specify numerical sorting, you should prefix the name of
the field (and follow the _x_ header, if any) with a number. The number will be used
for sorting, but will not be displayed in the email. For example,

	_3_4CardNumber
	2HomeAddress
	_4_3EmailAddress
	1UserName

The above fields, if _1_SortFields was set to 2, would be output in the following way
in the email:

	UserName
	HomeAddress
	EmailAddress
	CardNumber
	

The logging options allow you to log all form submissions to a continuously growing
file. You can use any combination of logging options together, and logging to a file
does not affect the sending of email. The value you provide for the logging fields
must be a valid filename that the web server process has write access to on your
system.

The _1_StripEmptyFields field causes all empty fields (not supplied by the user) to
be removed from the form output.

The _1_AcceptedCards field lets you specify which credit cards you can accept. If a
card number is entered for a _3_ field that is not one of the cards you accept, the
_1_CardNotAccepted document is shown to the user. To specify the cards you can
accept, you must add the required values from the following table and specify that
as the value for the _1_AcceptedCards field:

	Mastercard		1
	Visa			2
	American Express	4
	Diners Club		8
	Discover		16
	JCB			32

For example, a business that accepts only Mastercard, Visa and Amex, would specify
_1_AcceptedCards=7.

You can use the _1_AcceptEmptyCardField to allow optional credit card values. If
field is provided, a user can leave a _3_ field blank and it will be accepted.

The _1_NoHotmail field lets you reject email addresses from "anonymous" email
providers, like hotmail.com, yahoo.com and bigfoot.com. If specified, and the user
enters one of these email addresses in a _5_ email field, the _1_NoHotmailDocument
is shown to the user. You can add your own 'bad' addresses by creating a file in
the cgi-bin directory called "mailform.bad" - put one bad domain on each line.

_1_INIFile lets you specify an alternative ini file to use (the default is "mailform.ini")

The new _1_ConditionalSuccessDocument field lets you specify the URL of a success
document, and redirect to that document based on the value of another field in the form.
You can have as many conditional success documents as you like. The syntax for this field
is:

    _1_ConditionalSuccessDocument=<field name>,<match string>,<URL>

For example,

    _1_ConditionalSuccessDocument=Product,ThemesCD,http://www.company.com/confirm.cd

If the Product field on the submitted form contained the string 'ThemesCD', then the
"confirm.cd" document would be shown to the user on success. If no conditional fields
match, the default _1_SuccessDocument is used.

The Ignore field (_2_) can be added to the name of any fields on the form, to cause
MailForm to ignore them. They will not be included in the email that is sent.
For example, you can give the Submit button the field name _2_Submit, to prevent
it being included in the email.


The Credit card number field (_3_) lets you verify that a credit card number
entered by the user is a valid card number (of course, it can only check that
the card number is valid, not that the card itself is valid!). If any field names
begin with _3_ MailForm will check to see whether the contents are a valid credit
card number. If not, the operation will fail and the _1_InvalidCardDocument file
will be served to the user.


Any fields marked as required (_4_) will cause the RequiredFieldDocument to be
returned to the user if the fields are not supplied.


The Email field (_5_) lets you verify than an email address is valid. Anything
entered in an email field is checked to see whether it conforms to the usual
pattern of a valid email address - it must have a @ character and contain no
spaces. You can also use the _1_NoHotmail field to reject email addresses from
anonymous email providers.


5. Templates

Template files are optional, and allow you to control precisely the output of
the form message.

Using the _1_MailTemplate field, you can specify an external template file which will
be used to generate the email message. Set the value of the _1_MailTemplate field to
the filename of the template file. If you don't specify a full path, MailForm will look
for the template file in the cgi-bin directory where the MailForm.exe program is kept.

The template file is a plain-text file containing embedded codes which instruct MailForm
to insert form values. The format is fairly straight-forward; here is a brief example:

----------------------------------------------------------------------------------
Test Template File.

Submitted at %MF_DATE% from %MF_REMOTE_ADDR%.

Name:    %Name%
Address: %Address%
----------------------------------------------------------------------------------

As you can see, to insert a form value in the message you enclose the value name with
percentage signs.

Also value on the form, including hidden values, can be used in the template. There
are also four pre-defined values:

	%MF_DATE%		Date and time of form submission
	%MF_REMOTE_ADDR%	User's IP address
	%MF_REMOTE_USER%	Remote user
	%MF_USER_AGENT%		The http client used

Values inserted in the mssage can be left or right padded with spaces. This is useful
for lining up multiple fields. To pad a field, use the following notation:

	%[-]xx.name%

The - sign is optional; if specified, it indicates left padding instead of right. xx is
the number of spaces, and name is the value name as usual. For example,

	%-20.Address%		The field would be left padded to be 20 characters wide
	%32.Phone%		The field would be right padded to be 32 characters wide

There is also a * marker, which is used for multi-line text fields. When specified,
it causes all lines on the field after the first one to be aligned with the first line.
For example,

	%*Comments%		Properly align a multi-line text field
	%Comments%		Multi-line field would not be aligned properly



6. The MailForm.INI file

MailForm v1.3 and greater now has the option of an external configuration file. This
file must be called mailform.ini, and placed either in the cgi-bin directory along with
the mailform.exe program, or the Windows or Windows System directory.

Currently the mailform.ini file consists of a single section, Settings, with several
optional parameters (the values given for each parameter below are just examples):

[Settings]
MailIntro=Submitted at %1 from %2
MailServer=mail.company.com
MailTo=me@company.com
SuccessDocument=http://www.company.com/success.htm
FailureDocument=http://www.company.com/failure.htm
InvalidCardDocument=http://www.company.com/badcard.htm
RequiredFieldDocument=http://www.company.com/required.htm
CardNotAcceptedDocument=http://www.company.com/wrongcard.htm
InvalidEmailDocument=http://www.company.com/bademail.htm
NoHotmailDocument=http://www.company.com/bademail.htm
FooterMessage=\n\nThis is a custom footer message!
TextLog=c:\logs\formslog.txt
HTMLLog=c:\logs\formslog.htm
CommaLog=c:\logs\commalog.txt
Status=303
RefererCheck=company.com

The MailIntro parameter allows you to change the introduction line of mail messages
that MailForm sends. Use %1, %2, etc, to insert information about the current message.
The codes available are:

	%1	Date & Time
	%2	Remote address
	%3	Remote user
	%4	HTTP agent (ie the user's Browser)

The MailServer parameter allows you to configure a global mail server for use with
MailForm. If the _1_MailServer line is not given in the form, the value supplied here
will be used as a default. You may want to use this if you don't want to make the address
of your mail server known publicly.

The MailTo, SuccessDocument, FailureDocument, InvalidCardDocument and
RequiredFieldDocument parameters all allow you to define the default values of the
equivalent system fields for all forms. If these values are not overridden on the form
itself, by use of the _1_ system fields, the default will be used.

The FooterMessage field lets you specify a text message that is added to the end of
all email that MailForm sends. It must be specified on one line, and the maximum
length of this message is 480 characters. Within the message, you can use the following
escape codes:

	\n	New line
	\t	Tab character

Please note that the FooterMessage field is only available if your copy of MailForm
has been registered. Otherwise, an internal footer message is used.

The TextLog, HTMLLog and CommaLog fields let you specify global logging files for form
submissions.

The Status parameter lets you define the status code that is returned by
MailForm to redirect the client to a new page. By default (if it is not given
in the mailform.ini file), no status code is used - MailForm returns a "parsed"
HTTP response. This is how you will usually leave it, as it is _supposed_ to
work for all servers and browsers.

However, some servers seem to not like the standard output MailForm generates.
Therefore, if you specify a Status line, MailForm will produce a "non-parsed"
HTTP response, using the status code you supply. Again, the actual status
code seems to vary from server to server. Status 303 _should_ work (it is the
one designed for this process), but some servers (eg Alibaba) don't seem to
like it. Try the following codes if you are having problems: 303, 302, 301,
201, 200.

The RefererCheck field can only be used from the .ini file. It lets you specify a string
that the "referer" of a form must match before MailForm will process the form. This can
stop unauthorised people setting up forms on their web sites and then using your copy of
MailForm to process them. If RefererCheck is not specified, anyone can access MailForm.
If you specify RefererCheck, it should be set to the usual web address of your web site
(eg www.company.com). Only forms from the specified web address will be able to be processed.

7. MailForm is Shareware

The unregistered version of MailForm is fully functional, however it does contain
a couple of reminders for you to register it. The first is a blurb at the bottom of
each email it sends for a completed form. The second is a brief message at the
bottom of the document served to the user for a successfully completed form.

If you register MailForm you will receive a program to unlock it and remove these
two messages. You will also be helping to support the author, and encourage the
development of more great software like this. See http://www.lss.com.au for more
information.


8. Release History

	v1.0     Aug 97	 - First public release

	v1.11 21 Aug 97  - _1_SuccessDocument, etc, can now handle URLs to
                           redirect to as well as document path names.

                         - A bug was fixed which would prevent email being
                           sent correctly if the mail server name given
                           contained more than three parts (eg xxx.yyy.com
                           would be ok, but www.xxx.yyy.com would fail)

	v1.2  26 Aug 97  - Closed off a potential security hole; the
                           _1_xxxDocument fields had the potential to be
                           used to return any file on your system if the
                           permissions of the HTTP server were set incorrectly
                           and someone used your copy of MailForm with their
                           own form. The _1_xxxDocument fields now only accept
                           a URL to the file to return - you will need to modify
                           your forms if you upgrade to 1.2.

                           Sorry for any inconvenience. If anyone specifically
                           needs the old behaviour of the document fields, please
                           contact me. 

			 - Added _4_ required fields, and the
                           _1_FieldRequiredDocument document to be served if a
                           required field is missing. Now only requests Windows
                           Sockets 1.1 instead of 2.0; should fix problems
                           people have had getting the email to work if they are
                           running a Windows 95 web server. 

	v1.3   4 Sep 97  - Added mailform.ini file support

	v1.4  27 Oct 97  - Now returns HTTP status code 301 when redirecting to
			   another page. This should fix the problems people have
			   been having with some servers (eg IIS4)

			 - You can now have multiple _1_MailTo fields in the form
			   if you want to send the mail to more than one address.

			 - _1_MailTo can now take multiple email addresses on the
			   one line, separated by commas.

	v1.41 28 Oct 97  - Added 'Status' option to MailForm.INI file.

	v1.42 28 Oct 97  - Added _1_CCMailFrom field.

	v1.43 30 Oct 97  - Even though since v1.2 MailForm only requested Sockets
			   1.1, it was still linked with ws2_32.lib, meaning it
			   still needed Sockets 2.0 to run. Now requires wsock32.dll
			   instead of ws2_32.dll, and should work fine under
			   Windows Sockets 1.1

	v1.5  30 Dec 97  - You can now specify the name of another field in the form
			   for the value of the _1_MailFrom field. The main use for
			   this is to specify the name of a field where the user
			   enters their email address. The mail would then appear
			   to come from the user.

			 - Added the MailTo, SuccessDocument, FailureDocument,
			   InvalidCardDocument and RequiredFieldDocument optional
			   parameters to the INI file.

			 - Added the ability for registered users to specify a
			   footer message for all email MailForm sends, using the
			   FooterMessage parameter in the INI file.

			 - Added the _1_SortFields field sorting option.

			 - The value of multi-line input fields is now aligned properly
			   with the field header in the email (previously, the first line
			   was indented but following lines were all right-justified).

	v1.6  29 Jan 98  - Added logging options

	v1.7  25 Mar 98  - New registration system implemented

	v1.8  22 Apr 98  - Added the CardNotAccepted, InvalidEmail and NoHotmail
			   document fields. Added the _1_StripEmptyFields option.
			   Added the _1_NoHotmail and _1_AcceptedCards options.
			   Added the _5_ email fields.

	v1.81  6 Jun 98  - There was a slight problem in the registration system that
                           would cause MailForm to report that the registration had
                           succeeded AND failed, at the same time.

	v1.82  7 Jul 98  - Slight change to the registration system

	v1.83 12 Jul 98  - Added RefererCheck option

        v1.9   6 Nov 98  - Implemented template system

                         - Added _1_INIFile, _1_MailIntro, _1_AcceptEmptyCardField
                           fields and the _1_ConditionalSuccessDocument system.

	v1.91 13 Jan 98  - Will now find the template file if it is in the cgi-bin
                           directory and the full path is not given (as documented).

                         - A bug which could cause a crash under some circumstances
                           fixed.


