Stalker's CGIMail V1.03 07.29.96 / Eric Voisard ==================================================== Copyright (c) Stalker Lab (SaRL), Switzerland All Rights Reserved. S T A L K E R SaRL Jaquet-Droz 18 2300 La Chaux-de-Fonds Switzerland phone: +41 39 225 666 fax: +41 39 225 667 email: tech@cdf.globalcafe.ch (soon: tech@stalker.ch) Stalker's CGIMail is freeware and can be freely distributed. The Software is provided on an "AS IS" basis, without warranty of any kind. Eric Voisard and Stalker Lab declines any responsability in the eventuality of damages caused by the use of this software. 1. INTRODUCTION --------------- Stalker's CGIMail as says its self-explanatory name, is a CGI program allowing a http server to send SMTP mail with data coming from a HTML form. As a 32bits app, it requires Microsoft Windows 95 or (better) Windows NT. 2. FEATURES ----------- The mail is based on template text files with variables in it, and stored in the server. When launched, Stalker's CGIMail loads a specified template, replaces the variables with data coming from HTML form, before to send the resulting text as mail body. Stalker's CGIMail allows multiple "To", "Cc" and "Bcc" recipients, and is MIME compliant (useful for countries other than US!). 3. INSTALLATION --------------- Stalker's CGIMail.exe must be installed in a CGI mapped directory on the server (not a winCGI one!). CGImail.ini must be in the same directory. Mail templates may be in other directories. 4. CALLING THE CGI ------------------ As a CGI 1.1. specs compliant program, Stalker's CGIMail is called with the POST method, like:
5. VARIABLES ------------ Variables are user defined and Stalker's CGIMail allows up to 1000 of them. They are words bracketed within '$' chars (e.g. $var$), they can be up to 32 chars long including '$'s. Variables are case sensitive, spaces are allowed but their use is discouraged. The names must be the same in the HTML form and in the templates. Stalker's CGIMail routine tries to find as many matches as it can between form names and templates variables, and replaces all what it can with form values. In example, HTML lines like these:
  1. I work on UNIX.
  2. I work on NT.
With a template line like this: Hi, I think $var1$! That's all what I have to say. Will give: Hi, I think NT is a good OS! That's all what I have to say. Or: Hi, I think I'm born to run UNIX! That's all what I have to say. An unique variable name can be used several times in the template, it will be replaced as many times as it appears. Note that if a template variable was not passed by form, it is not treated and is sent "as is" in the mail. If a form field doesn't have any matches in the template, it is ignored. 6. RESERVED VARIABLES --------------------- Some variables are reserved words for internal use. Some are not needed, others must be specified in the form. They are: $File$ NEEDED! Name and pathname of the template to be used with the current form. (! If no local path is specified, CGImail will check in its directory) $LocationOK$ NEEDED! The URL to go if mail is correctly sent. (! If no URL path is specified, CGImail will check in its directory) $LocationKO$ NEEDED! The URL to go if an error has occured and mail is not sent. (! If no URL path is specified, CGImail will check in its directory) $Subject$ Not needed Subject of the mail which appears in the mail header. $Sender$ Not needed Overrides sender's address of CGImail.ini (see CGImail.ini). $Realname$ Not needed Overrides sender's real name of CGImail.ini (see CGImail.ini). $Optional$ Not needed For optionally passed values from form (see below). $To$ At least ONE IS NEEDED A normal "To:" mail recipient. $Cc$ Not needed A "Carbon-copy" mail recipient. $Bcc$ Not needed A "Blind Carbon-copy" mail recipient. User can specifie more than one $To$, $Cc$ and $Bcc$ recipients in the form, but not more than 100 recipients at all. These variables (and others) will not appear on the client's browser if "hidden" is specified in the HTML form source. 7. OPTIONAL VALUES ------------------ Some of the name/value pairs on the form are not necessary passed to the CGI by the httpd. In example, an unchecked checkbox will neither send a value, nor its referencing name. This causes garbage in the resulting message because the CGI does not find any match for corresponding template variable, and send it "as is" in the mail. To allow the use of such optional values, the reserved variable $Optional$ can be specified in the form, with a default value string. In the template and the form, a prefix "Opt." must be appended in the concerned variables names (e.g. $Opt.MyCheckBox$). Then, if the CGI find the $Optional$ reserved variable, it will replace all remaining $Opt.$ variables with the default value string. Usually, a NULL string will be used as default string. 8. TEMPLATES FILES ------------------ Templates are simple texts that can be edited with the Windows Notepad in example. Since Stalker's CGIMail is MIME compliant, extended chars and charsets other than 7 bits US-Ascii can be used. There is no limit with the file size, but each line can't be longer than 1000 chars and MUST be ended with CR/LF (Carriage-Return and Line-Feed). Note that UNIX style (LF alone) will work, but Macintosh type (CR alone) will not. Templates can be stored anywhere in the Web server, but paths (local paths!) must be specified within the $File$ form variable. 9. CGIMail.ini -------------- Some setting must be specified in the .ini file: Gateway= Name of the SMTP relay Sender= Email address of the sender which will appear in the "From:" field of the mail header. An idea is to set the webmaster's one, so if the mail bounces, he is informed. Realname= Real name of the sender which will also appear in the "From:" field of the mail header. Can be used to specify that mail comes from a CGI. MIMEncode= This is a MIME encoding parameter. Stalker's CGIMail uses MIME specs declarations and encoding. If MIMEncode=no, mail will be sent 8bits MIME to the mail relay without encoding. If MIMEncode=yes, mail will be sent 7bits Quoted-printable MIME encoded. This setting depends on the mail relay capabilities to handle 8bits chars, but it is more reliable to force 7bits encoding. Charset= Specifies the local charset used (e.g. US = us-ascii; Latin = iso-8859-1) 10. LOGGING THE PROCESS ---------------------- Each time Stalker's CGIMail is called, it creates or overwrites CGIMail.log in the CGIMail.exe directory. All the process and the dialogs with the SMTP gateway are stored in this file. This is useful for debugging when errors occur or just to verify the process. 11. WHEN AN ERROR OCCURS ------------------------ If an error occurs, the client's browser is redirected to $LocationKO$. When possible, the error is specified in the log file (it's a good idea to check it, times to times). If the mail message was present before the error occured, or if the mail was not or partially sent for any reason, it is appended to the file dead.letter.txt. So it is possible to handle it manually as a last resort. The only error which can't be logged is the CGI unable to handle the log file! If the CGI can't open the log file, the process is aborted and the client receive a brief message asking him to inform the webmaster. So, if you never receive mail from the CGI, or if errors seems to occur but nothing is logged, turn around the log file to fix the problem. 12. REFERENCES -------------- [1] J. Postel, "SMTP (Simple Mail Transfert Protocol)", RFC 821, ISI, August 1982 [2] Crocker, D., "Standard for the Format of ARPA Internet Text Messages", STD 11, RFC 822, UDEL, August 1982. [3] Borenstein N., and N. Freed "MIME (Multipurpose Internet Mail Extensions) Part One: Mechanismsfor Specifying and Describing the Format of Internet Message Bodies", RFC 1521, Bellcore, Innosoft, September 1993. [4] K. Moore "MIME (Multipurpose Internet Mail Extensions) Part Two: Message Header Extensions for Non-ASCII Text", RFC 1522, University of Tennessee, September 1993. [5] D.R.T Robinson "The WWW Common Gateway Interface Version 1.1", IETF Internet-Draft, University of Cambridge, 15 February 1996 13. HISTORY ----------- 07.29.96 Version 1.03 -Added internal variables to override sender's address and real name of CGImail.ini. -Added a date stamp on messages appended to dead.letter.txt for better management. 07.24.96 Version 1.02 -Improved the MIME conversion routine. -Added optional form values handling. 07.10.96 Version 1.01 -Fixed minor bug causing inappropriate error message. -Changed a test causing the sending (RCPT TO) of recipient list to be stopped a first incorrect one, and mail to be unsent to remaining correct recipients. Now, all valid recipients will receive their mail. 07.02.96 Version 1.00 -First release