Uitgebreide uitleg gebruik CGIMAIL

CGIMailer is an CGI (Common Gateway Interface) program wich will recive input from web form and send mail.

Using CGIMailer

CGIMailer is controlled with configuration files (form.cf). You can setup following variables in configuration file:

TEMPLATE REQUIRED is relative path (from CGIMail.exe) to template file used to create response page if operation succeeds. If this variable is not set CGIMailer will generate an error. (http://wwww.domeinnaam.nl/cgimail/cgimail.exe

ERRTEMPLATE relative path to template file if an error ocures. If this variable is not set CGIMailer will display an built-in error message.

MSGTEMPLATE template for creating mail message. If this variable is not set CGIMailer will create message of following form:
VARIABLE1=VALUE1
VARIABLE2=VALUE2
...
Where VARIABLE1, VARIABLE2 etc. are names of input fields in your web form.

DEBUG If this variable is set to YES (DEBUG=YES) CGIMailer will send an text response with transcription of comunication with SMTP server. Othervise it will create response page based on file pointed in TEMPLATE variable.

GATEWAY Name of smtp server (smtp.server.com for example) to use for sending mail. If this variable is not set CGIMailer will assume localhost.

PORT Port number of SMTP service on SMTP server. By default it is 25.

FROM E-mail address of sender. If this variable is not set CGIMailer will assume an addres of form CURRENT_USER@NAME_OF_LOCAL_MACHINE. You should set this variable in most cases.

TO REQUIRED E-mail addres (or list of addresses) of recipient(s). If this variable is not set CGIMailer will generate an error. E-mails have to be separated with space (" ").

CC List of addresses to send carbon copy of message (displayed in Cc: field of message).

BCC List of addresses to send blind carbon copy of message. Addresses listed in this line will not be listed in header of message.

SUBJECT Subject of message.

TIMEOUT Timeout (in seconds) for socket operations. Default is 300.

Name of configuration file can be passed to CGIMailer in two ways:
- By setting SYS.CONFIGFILE on Your form. Your caling HTML code should look as follows:
. . .
- Or by passing name of configuration file as command-line parameter:
. . .

NOTE: path to configuration file must be relative to directory where cgimail.exe is placed, or absolute path (with drive letter). Also use SYS.CONFIGFILE variable when using GET method.

You can also call CGIMailer from tag with

or

or

Variables

CGIMailer will proccess configuration file, response template file and message template file (if any) to check for variables to be replaced. Variables should appear in following format:

CGIMailer recognises four types of variables:

- Required variables Required variable names must start with "REQ." (REQ.name for example). When CGIMailer finds required variable in any of following files: configuration file, response template file or message template file, it will check if variable is passed from form and if it contains any characters other than spaces. If not so CGIMailer will generate an error. CGIMailer will also check input from form for required variables.

- System variables System variable names begin with "SYS." prefix. Folowing system variables are present in CGIMailer:

SYS.YEAR - current year.
SYS.MONTH - current month.
SYS.DAY - day.
SYS.HOURES - hour when CGIMailer is started.
SYS.MINUTES - minit when CGIMailer is started.
SYS.SECONDS - second when CGIMailer is started.
SYS.TEMPLATE - name of response template file.
SYS.ERRTEMPLATE - name of error template file.
SYS.MSGTEMPLATE - name of message template.
SYS.MAILER - name of mailer (defaults to: CGIMailer version 1.00)
SYS.INPUT - preproccesed message wich is sent.
SYS.GATEWAY - name of SMTP server.
SYS.HOST - name of local host (where CGIMailer is executed).
SYS.PORT - port number used to connect to SMTP service.
SYS.FROM - E-mail addres of sender.
SYS.TO - E-mail(s) of recipient(s).
SYS.CC - Addresses listed in Cc: field.
SYS.BCC - Bcc list of addresses.
SYS.SUBJECT - Subject of message.
SYS.TIMEOUT - Timeout for socket operations in seconds.

- Environment variables Environment variable names begin with "ENV." prefix. CGIMailer will replace every occurance of variable beginning with "ENV." prefix with coresponding environment variable. For example occurance of ENV.TEMP variable will be replaced with environment variable TEMP passed by OS (contains name of default temporary directory on your system).

- Occurance of any other variable (not beginning with REQ., SYS. or ENV. prefix), will be simply replaced with its value.

Error template
-----------------

When an error occures (and if ERRTEMPLATE variable is set in configuration file) CGIMailer will use error template file to create an response to user. Error template file is an HTML document with directives of following form:

where NN is error code of error wich occures or one of keywords "default" or "end" For list of error codes generated by CGIMailer see errcodes.txt. When proccesing error template CGIMailer will create an HTML document from following parts of error template file:

- beginning of document untill first , directive, or end of file if there is no any error directive.

- section wich begins with directive (where NN is error code of error generated by CGIMailer if such directive) or directive if there is no an appropriate directive, and ends with any other error directive or end of file if no error directives are listed after this one.

- section wich begins with directive and ends with end of file.

0 - Reserved

1 - CONTENT_LENGTH variable is not passed. When HTTP server executes an CGI program it is supposed to pass CONTENT_LENGTH environment variable to program. This error may occur due to server error. On this error CGIMailer always responses with internal error message.

2 - Error reading STDIN. This error is generated if CGIMailer can't read number of bytes specified in CONTENT_LENGTH variable. On this error CGIMailer always responses with internal error message.

3 - Not enough memory. This error occurs if CGIMailer fails to allocate memory required to operate properly.

4 - Name of configuration file is not passed. CGIMailer expects name of configuration file to be passed as command line parameter or in SYS.CONFIGFILE variable. If this is not case it generates error with this code. If this error occurs check calling HTML code to see if the name of configuration file is correctly passed, also be sure to use POST method for calling CGIMailer. On this error CGIMailer always responses with internal error message.

5 - Syntax error in configuration file. This error is generated when CGIMailer finds unexpected line in configuration file. Also check if all variable names in configuration file are written correctly.

6 - Reserved

7 - Error reading configuration file.

8 - Error reading response template. This error is generated when response template is successfully opened but CGIMailer can't read complete file.

9 - Error reading error template. This error is generated when error template is successfully opened but CGIMailer can't read complete file. On this error CGIMailer always responses with internal error message.

10 - Error reading message template. This error is generated when message template is successfully opened but CGIMailer can't read complete file.

11 - Internal error

12 - Error opening response template. This error is generated when CGIMailer fails to open response template. If this error occurs check if TEMPLATE variable points to an existing file, also check access permissions for that file. All variables pointing to files are expected to contain path relative to cgimail.exe or an absolute path.

13 - Error opening message template. This error is generated when CGIMailer fails to open input template. If this error occurs check if MSGTEMPLATE variable points to an existing file, also check access permissions for that file. All variables pointing to files are expected to contain path relative to cgimail.exe or an absolute path.

14 - Error opening error template. This error is generated when CGIMailer fails to open error template. If this error occurs check if ERRTEMPLATE variable points to an existing file, also check access permissions for that file. All variables pointing to files are expected to contain path relative to cgimail.exe or an absolute path.

15 - Error opening configuration file. This error is generated when CGIMailer fails to open configuration file. If this error occurs check if name of configuration file passed to CGIMaier points to an existing file. All variables pointing to files are expected to contain path relative to cgimail.exe or an absolute path. On this error CGIMailer always responses with internal error message.

16 - Reserved

17 - Reserved

18 - Reserved

19 - Failed to sent mail. This error is generated when CGIMailer can't send mail for an unknown reason.

20 - Reserved

21 - Reserved

22 - Sender not acceptable. SMTP does not accepts address stated in FROM variable as valid.

23 - Recipient not acceptable. SMTP server refuses one(or more) address(es) listed in TO, CC or BCC.

24 - Required variable is not set. This error will be generated if CGIMailer finds required variable with value which is not set.

25 - Reserved

26 - Reserved

27 - Reserved

28 - Reserved

29 - TEMPLATE variable is not set. CGIMailer generates this error when TEMPLATE variable in configuration file can not be found.

30 - Reserved

31 - TO variable is not set. CGIMailer generates tihs error when TO variable in configuration file can not be found.

32 - Reserved

33 - Reserved

34 - Reserved

35 - Reserved

36 - Connection timed out. There was no response from server whithin TIMEOUT seconds. See TIMEOUT variable in configuration file.

37 - Connection reset by SMTP server.

38 - Invalid TIMEOUT value.

39 - Failed to initialise Windows socket subsystem.

40 - Network is down.

41 - Host is unreachable. This means that CGIMailer cant't reach SMTP server specified in GATEWAY variable in configuration file.

42 - Connection is refused. SMTP server specified in GATEWAY variable in configuration file refuses conections on specified port (PORT variable).

43 - Network is unreachable.

44 - SMTP server can not be found. CGIMailer can not find SMTP server's IP address.

45 - SMTP connection failed. CGIMailer generates this error when is connected to server but SMTP conversation failes.

46 - Unknown network error. An network error occured while sending mail.