MailForm v1.6 (c) Copyright 1997 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 four different type of MailForm fields: _1_ System field _2_ Ignore field _3_ Credit card number field _4_ Required 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_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_CommaLog Set this to log all form submissions to a comma-delimited text file 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 four documents, Success, Failure, InvalidCard and RequiredField 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 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. 5. 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 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 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. 6. 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. 7. 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