1. What is Mailer
2. Modifications
3. Version History
4. Compilation
5. Installation
6. Configuration
7. Command Line Options
8. Form Requirements
9. Error List
10. Trouble Shooting
11. License
12. Contact Information

Mailer is a cross-platform CGI program written entirely in C++. Its purpose is to read data from HTML forms that call it, display the results on a "receipt" page, and send the information to a specific e-mail address. It was designed to run equally well on servers running Windows and Linux using any HTTP service. It is fully configurable, has built in features that prohibit the running of arbitrary code, and will prevent outside servers from executing it.


II. MODIFICATIONS

This is an official release of Mailer and, therefore, no modifications have been made.


III. VERSION HISTORY

01/25/2004 -- Version 2.55 (New Year)

• Fixed a bug that prevented Mailer from sending mail through some SMTP servers.
• Added a version flag to display version information.
• Added a license flag to display the license information.

11/07/2002 -- Version 2.5 (Complete)

• Added the domain line to the configuration file because some mail servers reject e-mail adresses without the @domain.name part.
• Reorganized some code and removed unneeded code and variables.
• Added more comments
• Put more code and variables that were platform specific in conditionally compiled sections. This code was not causing problems, but did not need to be compiled.

11/03/2002 -- Version 2.2 (Vacation)

• Added a trouble shooting section to the manual.
• Placed all of the version information in a header file (version.h) to make updating it easier.
• Reorganized some code and removed unneeded code and variables.

10/31/2002 -- Version 2.0 (Dracula)

• Gave the release a name.
• Changed the manual to HTML for improved readability across multiple heterogenous system architectures.
• Added a test form to the distribution.
• Changed wording in the manual for more clarity.

09/20/2002 -- Version 1.9

• Removed unnecessary variable passing between functions in the same class.
• Fixed a problem that could occur when reading the last line of the configuration file, if there was no carriage return at the end.
• Made some more changes for cross platform compatibility.
• Reorganized some code and removed unneeded code and variables.
• Reordered two lines so that the connection to the mail server would be closed before Winsock was shutdown on Windows systems.
• Added more comments.

09/19/2002 -- Version 1.8

• Fixed a buffer overflow problem caused by recent changes. Memory that was never actually allocated was being written to in some (rare) instances.
• Removed some unneeded include statements.
• Modularized the code some more. Used classes much more extensively to make the code easier to maintain and harder to break.
• Optimized the code slightly by removing extra parameters in function calls when the code was converted to use classes more extensively.

09/18/2002 -- Version 1.6

• Reorganized several lines of code for improved readability.
• Made several variable names more meaningful.
• Added more comments.
• Most types were put into the new header file mtypes.h.
• Cleaned up some more deprecated (C-style) code and used more modern C++ conventions.

09/17/2002 -- Version 1.5

• Added more memory protection by using constants in function definitions where applicable.
• Cleaned up some more deprecated (C-style) code and used more modern C++ conventions.

09/13/2002 -- Version 1.4

• Changed the code so that the path to the configuration file (mailer.conf) no longer needs to be hard coded at compile time. This file does need to be in the same directory as the executable though.
• Changed some of the code so that unnecessary warnings were no longer produced in Borland C++ (and possibly other compilers).

09/11/2002 -- Version 1.2

• Cleaned up some deprecated (C-style) code and used more modern C++ conventions.
• Enabled the use of a host name for the e-mail server instead of just an IP address.
• More changes for increased portability.

09/09/2002 -- Version 1.1

• Changed some of the define statements for portability and readability.
• Added more comments.

10/15/2000 -- Version 1.0

• First official release.

This program should compile on Windows NT 4/2000/XP and Linux with no modifications. This program should also compile successfully on many *IX operating systems with very few changes.

Linux using g++

1. Run make

Windows using Borland C++ 5.2 or C++ Builder

1. Run the batch file (comp.bat) that should be included with this distribution.

That's all there is to it.


V. INSTALLATION

To install Mailer, copy the executable (mailer.exe in Windows and mailer in *IX) and the configuration file (mailer.conf) to the cgi-bin directory of your web server.


VI. CONFIGURATION

mailer.conf is the configuration file for mailer. This file allows the user to set certain options including the IP address of the mail server to connect to, the port to connect to, and a list of server names and IP addresses that will be allowed to use this CGI.

The format of this configuration file is straight forward; A pound sign (#) at the beginning of a line indicates that the current line is a comment. PORT: xxxx tells Mailer which port to connect to. IP: xxx.xxx.xxx.xxx tells Mailer what the IP address of the mail server is. This value may now also be a server name; Mailer will attempt to look it up. VALID: xxx.xxx.xxx.xxx1 ... xxx.xxx.xxx.xxxN lists servers that will be allowed to call this CGI; this ensures that other sites cannot use your server to process their forms. DOMAIN: is the domain name for the site that Mailer is being run from.

All three of the above pieces of information must be included in the configuration file for Mailer to run. No line may be longer than 80 characters. If more valid addresses than will fit on a line need to be listed, they may be placed on subsequent lines. These lines must also begin with the keyword VALID:.

For more information, please examine the comments in the included example mailer.conf.


VII. COMMAND LINE OPTIONS

As of version 2.5, two command lines have been added. To display the license information, use the -l or -L command line option. To view the version number, use the -v or -V command line option.


VIII. FORM REQUIREMENTS

What method is used to send data? The "post" method must be used for the HTML form to correctly pass data to the CGI. This method was chosen over the "get" method for several reasons. Get allows only a limited amount of information to be passed to CGI, whereas post allows an almost limitless amount of data to be sent. Get displays all sent information in the URL line of the web browser; this is, in my opinion, annoying and may show the user information that they should not see (hidden fields for instance).

Are there any required fields? Yes. Mailer requires several fields to always exist in the calling form. Unless there is a specific reason to do otherwise, these fields should normally be hidden. MailTo contains the e-mail address that the form's contents should be sent to. Subject contains the subject line for the e-mail message.

Are there any optional fields? Yes. Link may be set to a web address. This address will appear on the receipt page so that the user may leave this page without pressing the browser's back button. If Link is specified, Description must also be set. Description is the text that the user may click on to follow the link. The Title field is used to indicate what title to display at the top of the browser; if none is given, "Receipt" is used.

For more information, please study the test form (mailer.html).


IX. ERROR LIST

1. The configuration file could not be found. Make sure that mailer.conf exists and is located in the same directory as the executable.
2. No port was listed in the configuration file. The configuration file did not list a port to connect to the mail server on. Check the configuration section for more information.
3. No IP address was listed in the configuration file. The configuration file did not list an IP address to connect to the mail server at. Check the configuration section for more information.
4. No valid server was listed in the configuration file. At least one server must be allowed to run mailer. Check the configuration section for more information.
5. Form data must be sent via the POST method. The get method can not be used to pass data to mailer. For more information, read the form requirements section.
6. No data could be read from the form. A form was submitted, however no data was transmitted to mailer. This could be due to a network error, or a problem with the form.
7. Unauthorized access to this CGI, please inform the webmaster. Mailer was called from a server that was not listed as valid in the configuration file. Make sure that all names and IP addresses are typed correctly in mailer.conf and ensure that all servers that should be able to run Mailer are listed. Also, make sure that the VALID: line is not longer than 80 characters. Check the comments in the configuration file for more information.
8. This CGI must be called from a form. This message normally means that Mailer has been run from the command line, rather than being called by the web server. Mailer will only run when called by a web server that was processing a form.
9. No recipient e-mail address was specified in the form. The form did not have a MailTo field; therefore, Mailer did not know who to address the message to. Ensure that this field is present and spelled correctly. Check the example form (mailer.html) for more information.
10. No subject was specified in the form. The form did not have a Subject field; therefore, Mailer did not know what to use for the subject line of the message. Ensure that this field is present and spelled correctly. Check the example form (mailer.html) for more information.
11. A link was present in the form, but no description was given. The form contained the optional Link field without have a Description field. Mailer could not determine what to call the link. Make sure that the Description link is present and spelled correctly. Check the example form (mailer.html) for more information.
12. Winsock could not be started. This problem can only occur on Windows machines. For some reason, Winsock could not be started. If other network services are also experiencing problems, reboot the computer.
13. Could not open a socket. Either there are no available sockets left (see your operating system's manual to learn how to increase this number), or there is a problem with the TCP/IP driver on the computer. Rebooting the computer may resolve this issue.
14. Problem connecting to the server. Mailer could not establish a connection to the mail server. Make sure that the server name or IP address and port are typed correctly in the configuration file. Try pinging the mail server and see if you receive a response. Try connecting to the mail server with telnet and see if it works properly.
15. No domain name was listed in the configuration file. The configuration file did not list a domain name. Check the configuration section for more information.

• I received an error server error when Mailer is called. Make sure that the web server has execute access to Mailer. Also, ensure that your configuration file is correct.

Copyright (c) 2002, Carson F. Ball
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions, and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
• Neither the name of the author or of other contributors may be used to endorse or promote products derived from this software without prior written permission.

Please send all questions, comments, ideas, suggestions, bug reports, bug fixes, etc. to the e-mail address below and include Mailer in the subject line so that my spam blocker does not delete it. Also, if you make modifications to Mailer, please send me a copy of the modified program with comments documenting what has been changed, and I may add your changes to the next "official" release. A list will be kept of all parties that contribute to the "official" release. This list will be distributed with all subsequent versions.

I will only release new versions under certain circumstances (major bugs are found, security holes are found, enough people request a certain feature, someone sends me a useful feature). The only other circumstances that a new version will be released under are if I need a new feature added, or if somehow I manage to acquire an abundance of free time and have nothing more exciting to do.

E-mail: cball5@hotmail.com


All trademarks mentioned are property of their respective owners.