Formmail.ASP Version 1.3 Documentation

Release Notes

1. Bugs fixed in version 1.2 

a)	Special Characters parsed into the e-mail output due to passing through the querystring have being removed and replaced with the correct characters.

2. Bugs fixed in version 1.3

a)	We've added support for a few more special characters that were missed in version 1.2.
b)	A Major Bug was uncovered that meant the e-mail would not be send unless a SENDER (email field was specified.) An error in the code meant that if this field was left blank the script would NOT replace it with a valid Sender! This causes most SMTP Servers to refuse delivery.  This was not an obvious bug as the client would see the script execute correctly and redirect without incident. If you are looking for undelivered mail, try the following directory on your server: c:\inetpub\mailroot\badmail. (Sorry about that!)

Getting Started

First you will need to unzip the contents of the package you downloaded. You then have three files:

1.	FormMail.asp - which you should place in a folder on your IIS web server with Script Only permissions.
2.	Testform.htm - an example form which you can use as an example
3.	formmail-readme.rtf - this document.

Pre-Requisites

·	Windows 2000 Server, Windows 2000 Professional, Windows XP 
·	IIS 5.0 or Higher
·	CDO.sys libraries installed
·	Active SMTP Service

Note Formmail.ASP will no longer work on Windows NT 4.0 Server.

New features

·	Formmail.ASP Version 1.3 uses CDOSYS.DLL instead of CDONTS.DLL this provides support for XP and .NET Servers as well as Windows 2000, however it removes support for Windows NT 4.0.
·	Basic E-mail Validation - The contents of the “email” field are checked they form a valid address. This is not to say that the script checks the email address or the domain actually exists. It just ensures that the email address is of the form: name@domain.ext <mailto:name@domain.ext>.
·	Required Fields - You can now require that certain form fields are completed before submitting the form. This feature was added for uses that don’t have the benefit of FrontPage Form Validation, Dreamweaver extensions or a knowledge of JavaScript.
Setting Up the Script

Once you have placed Formmail.asp in the appropriate directory. Open the Formmail.asp file in your favourite text editor (Word Pad or NotePad) or open it with Dreamweaver or HomeSite in code view. [Relax this bit is easy!]

Scroll down the page until line no: 47 where you will see a line which starts with an apostrophe:

'############################ CONFIGURATION VARIABLES #############################

The first line you will need to change is line 54 

url = Array("www.your-domain.com","your-domain.com")

Here you simply replace www.your-domain.com and your-domain.com with the domain names you want to be able to access the script.

Save your changes.  This is the default set-up and will work in most cases. If it doesn’t see the Advanced Considerations below:

Setting Up the Form

The first step is to set the form action and method in the <form> tag. This should be set as follows:

<form method="GET" action="formmail.asp"> 

Naturally you modify the action to point at the full or relative URL of your formmail.asp script, the above example assumes that formmail.asp is in the same directory as the form you are setting up.

IMPORTANT THE FORM ACTION MUST BE SET TO “GET”. 

There six predefined form fields that you should ensure are present in your form in order to achieve maximum benefit from FormMail.asp Here's how to set them up:

<input type="hidden" name="recipient" value="you@your-domain.com">
<input type="hidden" name="redirect" value="http://www.your-domain.com/success.htm>
<input type="hidden" name="subject" value="Subject line of the e-mail to be sent">

Generally these three fields will be "hidden" unless you want the user to specify where the e-mail is sent it is ill advised to do otherwise. Note the redirect field is used to redirect the user to the successful form submission page. Without the recipient or the redirect fields specified the form will fail!

The three other fields are optional but very useful:

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

This captures the senders e-mail address. Useful if you want to be able to just click reply in your e-mail client and compose a response to form submissions.

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

This captures the senders name, it is always the first field displayed in the Outputted e-mail.

<input type=”hidden” name=”required” value=”textfield1, textfield2”>

This hidden field is used to ensure that the field names listed, (textfield1, textfield2) are “Required” fields. That is to say the form will NOT send without them. Please note this only works for textfields and it only requires an entry in them, it does NOT validate the data entered.

You can add as many other form elements as you like. FormMail.asp will parse through, text fields, menu/list boxes, checkboxes and radio buttons.

Finally you will need a Submit button on your form, the following html creates one and closes the form tag:

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

All that remains is for you to test your implementation on your web server.

Troubleshooting
Problem or Error Message
Formmail.asp executes successfully and redirects the user to the correct page. Only no email is sent.

Or 

Formmail v1.3 detected the following errors:
error no.: -2147220973

Solution
description: The transport failed to connect to the server
This generally occurs when the Specified SMTP Service is disabled, by default the script uses the SMTP Service running on the web server at port 25 this will normally be the IIS SMTP Service, if this fails contact your hosting provider to discover the IP Address and Port number of a working SMTP Service. You will then need to modify the strserver variable described below.

To save the call to your host its often worthwhile trying the SMTP Server of the “recipients” mail account, this can be found in Outlook (Express) by selecting Tools> Accounts Selecting the Mail account and clicking Properties and then looking at the server tab. EG: mail.yourdomain.com or smtp.yourdomain.com.

Problem or Error Message
Invalid Referrer Please check the referrer’s array in the Formmail.asp script .

Solution
This means you set up the referrers array incorrectly, check the URL of the form ensure that the address of the website submitting the form appears in the referrers array.

Problem or Error Message 
Formmail v1.3 detected the following errors.
Error no.: -2147220979
description: At least one of the From or Sender fields is required, and neither was found.

Solution
You have a version of Formmail.asp with a bug in it that we accidentally released! Download the latest version of the script to correct it.

Advanced Considerations - Network Admins/Web Hosting Providers

Formmail.asp uses the cdosys.dll, a built-in ASP component which generates the e-mails. Once generated the e-mails are sent using the IIS SMTP Service. Consequently this service must be enabled for the e-mails to be sent using the default set-up.

You can alter the SMTP Service that is used to deliver the forms by modifying the strServer and intPort variables defined on lines 51and 52

strServer simply defines the IP Address or the Computer name of SMTP Server, by default it is set to use the local machine: (127.0.0.1) You can change this to another mail server by altering the value eg:

strServer = "172.26.0.5" or strServer = "smtp.your-domain.com"

The intPort variable specifies the TCP Port on which your SMTP Server is listening, by default this will be Port 25. In most situations this will be correct

intPort = 25 

Generally there is no need to adjust this, but it remains useful if you want have the IIS SMTP Service running on the same machine as another commercial mail server, for example: MDaemon, Imail or MailMax. You can easily set the IIS SMTP Service to run on Port 26 and change the intPort variable to be equal to 26 as well. That way IIS handles the delivery of the mail. 

You may ask why not just use the commercial mail server? Well you could but that generally won’t allow you to relay mail destined for foreign domains. IIS’s SMTP Server will! However, we recommend standard security practices such as limiting the IP addresses of machines that can use or relay mail through the IIS SMTP service to the local machine. ie: Deny all connections that don't originate from the IP address of the local machine.