Stalker's CGImail V1.11          11.05.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 32 912 5666
fax: +41 32 912 5667
email:	tech@stalkerlab.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!). It allows
multiple files attachments.



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.

The app creates temporary files for attachments, so it's better to have
a TEMP or TMP environment variable.

Note:
If your httpd runs as SYSTEM user (and not as a custom pseudo-user),
the environment variables must be "system" (not "user") ones, and
must be set from "Control Panel" > "System" > "system environment variables". 



4. CALLING THE CGI
------------------
As a CGI 1.1. specs compliant program, Stalker's CGIMail is called
with the POST method, like:

<form method=POST action="/cgi-bin/CGIMail.exe">



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:

<ol>
<li><input type="radio" name="$var1$" value="I'm born to run UNIX">
I work on UNIX.
<li><input type="radio" name="$var1$" value="NT is a good OS" checked>
I work on NT.
</ol>

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)

$LocationReq$	Not needed
The URL to go if requested values were not filled as wanted. (See below)
(! 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).

$Attach$	Not needed
Name and pathname of a file to be attached with the message.
(! If no local path is specified, CGImail will check in its directory)
(See below)
Up to 100 attachments can be done.

$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.<name>$ variables with the default value string.
Usually, a NULL string ("") will be used as default string. 



8. REQUESTED VALUES
-------------------

In a same manner as Optional values, you may want some name/value pairs
to be requested, and to return an error if the form is not completely
filled as you wanted it to be.
For such Requested variables, in the template and the form, a prefix
"Req." must be appended in the concerned variables (e.g. $Req.MyName$).
If specified, an hidden variable $LocationReq$ can be used, allowing
a special html page to tell the client to correctly fill the form. If not
specified, the location will be LocationKO.



9. ENVIRONMENT VARIABLES
------------------------

Some NT environment variables passed by the web server can be of some
utility in the mail generated.
In the template file (and not in the form), a prefix "Env.", followed
by the complete name of an environment variable can be used.
(e.g. $Env.REMOTE_ADDR$). CGImail.exe will then try to replace it with
the value it found. If the variable was not passed by httpd, CGImail.exe
put "Not available" at its place in the mail body.
Environment variables are not necessary passed by httpd, it's up
to you to check which ones can be used in your site.

Some well known variables are:

REMOTE_ADDR	:Remote IP address		
REMOTE_HOST	:Remote hostname
REMOTE_IDENT	:Connection informations in case of access authentication
REMOTE_USER	:User ID in case of access authentication
HTTP_USER_AGENT	:Remote browser and Operating System

Note: by convention, environment variables are uppercase.



10. 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.



11. ATTACHMENTS
---------------
Up to 100 files can be attached to the message to be sent. The values
of each $Attach$ variable must be a local path (no URLs!); they can
eventually be UNC paths pointing to another computer within the local
network (i.e. \\station2\shared\thefile.txt).



12. CGIMail.ini
---------------

Gateway=
Name of the SMTP relay

Sender=
Email address of the sender which will appear in the "From:" field of
the mail header. 

Realname=
Real name of the sender which will also appear in the "From:" field of
the mail header.

Textencode=
This is a MIME encoding parameter. Stalker's CGImail uses MIME specs
declarations and encoding.
If Textencode=no, mail will be sent 8bits MIME to the mail relay without
encoding.
If Textencode=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.

AttachInline=
Some mail readers allow to append attachments like images or HTML on the
message. This setting specifies if attachments must be handled as
separate files, or if they can be showed in line, within the message. 

Charset=
Specifies the local charset used (e.g. US = us-ascii; Latin = iso-8859-1)


The [MIME Types] section specifies some well known MIME types, based
on files extensions. When CGImail.exe doesn't find any matchs with
the file to be attached, it uses application/octet-stream as default.
Adding new MIME types is allowed, but be sure to add corrects MIME types.
If you plan to use some private types for internal use, you must append
the prefix "X-" to your type, i.e:

yours=application/X-yours

So files with .yours as extension can be handled as you want by some mail
readers understanding X-yours.



13. 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. 



14. 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 errors which can't be logged are the CGI unable to handle the
log file or incorrectly launched! 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.

Be careful to name correctly URLs and pathnames (i.e long names with
spaces must be quoted as "c:\temp\my file.txt". Partial paths are
relative to CGImail.exe working directory.
Be also careful about your server's rights, CGImail.exe must have
sufficient access rights on the files it works with.



15. 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



16. HISTORY
-----------

11.04.96	Version 1.11
- Fixed a bug causing attachments errors to generate an httpd error
instead of a LocationKO.
- Fixed a bug causing a NT "Access Violation" error if the variable
$file$ was incorrect in form.
- Modified the code to allows unbuffered writes in the log file, so
in case of CGImail crash, there will be more infos in the log file.
- Fixed a bug causing Real name and Email address of CGImail.ini not to
be overrided by form variables $Sender$ and $Realname$ in some cases.
- Added the ability to use in templates, the httpd environment
variables passed to CGI.
- Added the ability to have "Requested" fields in form.

10.23.96	Version 1.10
- Added the ability to send files as attachments.
- Added base64 encoding for attachments.
- Changed the structure of CGImail.ini, allows to add MIME types.
- Fixed a minor bug in Quoted-Printable '=' char encoding.
- Fixed a bug causing some error messages to be printed on console
even when console is redirected to a file.
- Suppressed the MIME encoding of headers with us-ascii charset so
that they are correctly handled by some 3rd mail apps.

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
