ASP Form Mailer Version 2.31

Author:  Matt Summers (matt@pd9soft.com)
         For more scripts & applications, visit
         http://www.pd9soft.com/

Version 2.3 And Above Updates by Blair Bonnett (blairb@paradise.net.nz)

-------------------------------------------------------------------------------------------------

Specifically selling this program without prior written consent is expressly forbidden.

For example, if you are a web developer, you _can_ use this program in a commercial site, but you
cannot itemize this script.  Use good judgment! We're providing this free for use, so should you.

aspFormMail.asp may be used and modified free of charge by anyone so long as this readme file is 
included with it, with this copyright notice and the comments remaining intact.  No warranties of
performance are provided.  Use this script at your own risk. You are NOT permitted to use this
script to send 'spam' messages to people.

-------------------------------------------------------------------------------------------------

History

 2.31 5/8/2003 : Added support for the CDOSYS email component
		 Added email override for cases where there is no referrer
  
 2.3 3/28/2003 : Added 'Anonymous' ToEmail
                 Added support for required fields
                 Added 'Friendly' Error messages
                 Improved e-mail checking
                 Tidied the code up
                  
 2.2 6/11/2002 : Added more mail component support
 
 2.1 10/23/2000: Revised QuickSort algorithim.
                 More changes to the referer code.
 
 2.0 7/31/2000 : Added support for ASPEmail component
                 Implemented alphabetical sorting with a quicksort algorithim
                 Revised the referer code
                 Add support for default e-mail addresses
 
 1.4 7/28/2000 : Added the referer security patch.  Should have done that a long time ago.
 
 1.3 5/13/2000 : Added the ability to print out fields in form-default order.
 
 1.0 2/19/2000 : Basic form created
   
-------------------------------------------------------------------------------------------------

Customizing ASP Form Mailer

1. Open the aspFormMail.asp file with Notepad.

2. Scroll down till you see the *** USER CONFIGURATION *** section

3. Change the information in that section as neccessary to suit your website.
   - Your mail server is where your outgoing mail is sent from; contact your host if you don't 
     know it. If you intend to use the CDONTS mail component, you don't need to specify this.

   - Allowed referers are the sites which can use the aspFormMail.asp file

   - Change the email component to whichever one is installed on your server; contact your host 
     if you don't know. At this point in time, supported options are:
     * "JMail" and "JMail4", both available from http://www.dimac.net/
     * "ASPEmail", available from http://www.aspemail.com/
     * "CDONTS" and "CDOSYS"
     
     It can easily be rewritten to support a new component; if you do this, please contact us so
     we can include that component in the next release.

   - The default from address will be used if the email address supplied by the user is invalid

   - The mail will be sent to the default to address if you don't specify one in the form

   - If the 'No referrer' option is set to true, then, if there is no referrer information 
     supplied by the browser, then the message will be sent to the default to address. This was 
     implemented because some firewalls were stripping this information out, and causing errors.
     If the referrer is available, then the script will still process it as normal.

4. See the Anonymous To-Email section further on for more information on what it is and how to 
   customise and use it.
-------------------------------------------------------------------------------------------------

Customizing The Error Message Pages

1. Open the MailHeader.inc file with Notepad. This file contains the text above the error 
   message.

2. Edit it to reflect the style of your website. The two neccessary things for it to have are the
   closing </head> tag and the opening <body> tag.
   
3. Save the changes and close the file.

4. Repeat with MailFooter.inc, which is the text below the error message. Make sure you change 
   the email link to point to your email address. This file must contain the closing </body> and 
   </html> tags.

-------------------------------------------------------------------------------------------------

Testing ASP Form Mailer

1. Right-click on the sample.html file and select Edit.

2. Change the email address in the ToEmail field to your address.

3. Change the web address in the RedirectURL field to a page on your site.

4. Upload aspFormMailer.asp, MailHeader.inc, MailFooter.inc and sample.html to the same directory
   on your website.

5. Point your browser to the sample.html file.

6. To test it fully:
   - Leave either the Name or Email fields (or both if you'd rather ;) ) blank, and it should 
     give you an error message.
   - Using the following (incorrect) email addresses should give you errors:
      * An address with the '@' as the first character
      * An address with the '@' as the last character
      * An address with no '@' in it altogether
      * An address with two '@' symbols in it
      * An address with no period after the '@'
      * An address with the last period less than two spaces before the end (incorrect suffix), 
        e.g. bob@there.c
      * An address with the first character after the '@' being a period
   - Make sure you get an email with the results if you fill it out completely
   - Edit the sample.html file and reupload it to check the Anonymous To-Email function works

-------------------------------------------------------------------------------------------------

Supported Variables

FromEmail:    The email address of who filled the form in. 
              <input type="text" name="FromEmail">
              The FromEmail will be checked by the script. If it is invalid, and 'NeedEmail' is 
              set to Yes, the user will be given an error message explaining why.
              If 'NeedEmail' is set to No, the only checking that will be done is if the length
              is zero; if that is the case, the default address will be used.
 
FromName:     Who filled the form in.
              <input type="text" name="FromName">

ToEmail:      Who the email will be sent to.
              <input type="hidden" name="ToEmail" value="you@your.domain">
	   or <input type="hidden" name="ToEmail" value="you">  
                (see 'Anonymous To-Email' for further information)

ToName:       The name of who the email will be sent to.
              <input type="hidden" name="ToName" value="Bob Smith">

EmailSubject: What the subject of the email will be,
              <input type="hidden" name="EmailSubject" value="Your form results">

RedirectURL:  The URL the user will be redirected to after filling your form out.
              <input type="hidden" name="RedirectURL" value="http://www.yourdomain.com">

Env_Report:   Sends a report of browser type, IP etc with the email; by default it is "No".
              <input type="hidden" name="Env_Report" value="Yes"

Sort:         The order the fields should be sent in. Can be "Alphabetical", "FormOrder" (the 
              order they are in your form, which is the default option) or user specified: 
              "field1, field2, field4, field3,..." etc.
	      <input type="hidden" name="Sort" value="Alphabetical">

Print_Config: The list of config fields to be sent in the email. Configuration fields are 
              "FromName" "ToEmail" "ToName" "Print_Config" "RedirectURL" and "Print_Blank".
              If none are specified, then none will be sent.
	      <input type="hidden" name="Print_Config" value="FromName,RedirectURL">

Print_Blank:  Should blank fields be emailed anyway? By default it is "No".
              <input type="hidden" name="Print_Blank" value="Yes">

Required:     The list of fields which the user must fill out before the form is mailed. If they 
              are not filled out the user will get an error message saying which ones need to be 
              filled.
              <input type="hidden" name="Required" value="FromEmail,FromName,Comments">

NeedEmail:    If the from email address must be valid; can be either "Yes" or "No", with the 
              default being No.
              If it is invalid with this set to "Yes", the user will be given an error message 
              explaining what is wrong with it.
              <input type="hidden" name="NeedEmail" value="Yes">

Notes:

1. Sort and Print_Config accept comma delimited values.
   <input type="hidden" name="Sort" value="FromEmail, Color, DogName, Age, BirthDate">
   
   Alternatively, for the "Sort" field, you can specify either "ALPHABETICAL" or "FORMORDER"; if 
   nothing is specified, "FORMORDER" is assumed by default.
   <input type="hidden" name="Sort" value="alphabetical"> 

   An unsorted, or alphabetically sorted list does not show any of the configuration variables 
   like ToEmail or FromName. 
   These are the "config variables" and are not shown be default.  You may specify to print 
   "config variables" by listing them in either the print_config or the sort fields.


2. Sort will print any form variable you supply, including Print_Config variables. You do not 
   need to specify BOTH a Sort and a Print_Config. 
   However, if you do not want to take the time to sort your variables (such as in a very large 
   form), yet you still want to view your config variables, then the Print_Config parameter 
   becomes useful.  When you list variables in the sort field, then only those are printed, the 
   rest are discarded.

   To recap, if you want to sort all your variables by hand AND show "config" variables, just 
   list all of them in the sort field and forget about the "Print_Config" field.
   If you don't feel like sorting all your fields by hand (such as in "ALPHABETICAL", or 
   "FORMORDER") and you still want to print out some of the "config variables", then just list 
   only the config variables in the "print_config" field.... Make sense? :)
  
3. Env_Report can be set to "YES" or "Y", case insensitive.  It reports all of the following:
   - Remote Address
   - Remote Host
   - Referring URL
   - User Name
   - Browser Type

4. The only required field is RedirectURL. The rest have defaults. However, combinations of 
   settings can prvide errors, so check your form carefully before publishing it. For instance, 
   if NeedEmail = "Yes", and you don't supply a box for the FromEmail, the user will get a 'You 
   didn't provide an email address" error message.

5. When using the CDONTS mail component, the ToName and FromName don't get used in the email.
   If you want to see them, you need to specify them in the "Print_Config" section. 
   Alternatively, when you ask a user for their name, you can call it something other than 
   'FromName'.

-------------------------------------------------------------------------------------------------

Anonyomous To-Email

This function comes in handy if you don't want to have your email address on the page of the 
form, where it is still available to spammers via View ==> Source and to 'spambots', which search
the HTML code for email addresses.


  Customising it:

Scroll down to the *** ANONYMOUS TO-EMAIL CONFIGURATION ***.
Just change "USER1" and "user1@yourdomain.com" (and USER2 of course) to whatever you want to use.

If the script finds that "USER1" (case insensitive) in the "ToEmail" variable of your form, it 
will replace it with "user1@your.domain".

To add more addresses for Anonymous To-Email, copy and paste the following as many times as 
neccessary before the "end if" in this section:

   ElseIf UCase(strToEmail) = "NAME" Then 
        strToEmail = "name@your.domain"

and then change it to the appropriate name and email address. It is very important to have the 
NAME IN CAPITALS, otherwise the script won't change it, so the emails will be lost in 
cyberspace...

In your form, the code will be <input type="hidden" name="ToEmail" value="Name">
The value is case-insensitive, so it could be "name" or "nAmE" or any other combination.


Disabling this function:
  You have two options:
- Delete the code between *** ANONYMOUS TO-EMAIL CONFIGURATION *** and *** END OF ANONYMOUS 
  TO-EMAIL CONFIGURATION ***; doing this will permanently remove this function.

- Comment out the code by placing inverted commas (') at the start of each line in the section;
  to re-enable it all you have to do is delete the inverted commas. Make sure the commas before
  the two lines beginning with *** are left though.

-------------------------------------------------------------------------------------------------

Support

If you are having problems with any aspect of this script, then head on over to the forums at
http://www.pd9soft.com/; in the 'aspFormMail' forum we will answer your questions.

-------------------------------------------------------------------------------------------------