Ŀ
                                                            
    Pegasus Mail v3.0 user-defined gateway reference.       
    This document is part of the Pegasus Mail manual set    
    and is provided as a courtesy to users of Pegasus       
    Mail.                                                   
                                                            
    Copyright 1992-93, David Harris, All Rights Reserved.   
                                                            



User-defined gateways
---------------------

Pegasus Mail version 2.25 and later incorporate a feature which 
allows you to implement your own mail transport and have PMail 
use it. The intention is that you will provide the mechanism 
for moving the messages and  attachments from place to place, 
while PMail does the preparation, formatting and filing for you.

Here are some possible gateways you could develop:

*	An implementation of uucp for dial-in Internet mail

*	A standalone gateway which communicates with a machine attached 
to your LAN, allowing you access to all your LAN mail features 
from a remote machine (such a gateway is currently under development 
as part of the PMail system).

*	A custom system which takes LAN mail and transfers it via some 
file transfer protocol to a mainframe.

*	A gateway to a facsimile server.

The possibilities are limited only by your imagination.


The gateway process.
-------------------

While PMail offers considerable flexibility in the way it can 
interact with your gateway, be aware that creating a gateway 
will almost certainly involve a small amount of programming - 
typically, you will need to write the program which PMail runs 
to deliver and receive mail. You can do this programming in any 
language which produces a program which could be run from DOS: 
Pegasus Mail is written in C, but you could easily write your 
gateway process in Pascal, Modula-II or even in Basic (God forbid!). 
PMail invokes your gateway process when sending mail, or to check 
for new mail. In most cases, your gateway process must not write 
to the screen.

Note: you can use MS-DOS batch files as gateway processes.

What the gateway process does, and how you should do it is not 
covered in this manual - this is your part of the project, and 
you'll have to design it to your own specification. As a help, 
however, the last section of this document describes how we interfaced 
PMail with Waffle, a popular BBS and UUCP program.


How PMail uses a UDG
--------------------

You have to provide PMail with a set of instructions which it 
uses to interface to your gateway. You do this using PMail's 
PCONFIG program, choosing "create a User-defined gateway". The 
gateway definition screen is essentially a form - you merely 
have to fill in the appropriate details for your gateway.


Command substitution
--------------------

Most of the entries in this screen which accept strings allow 
you to use special command substitution characters in the strings: 
these are like "escape sequences" which will cause PMail to perform 
some substitution at run-time. Command substitutions always begin 
with a tilde (~) character, and are always two characters long. 
The following command substitutions are recognised:

   This sequence...   Is replaced with this value

   ~c       The full path to the file containing the message
   ~t       The address to which to send this message
            (note: this is not necessarily the To: field)
   ~s       The message's subject field
   ~f       The full form of the message's "from" field
   ~n       The sender's user name in its simplest form
   ~b       The sender's bindery id, as a long hex integer
   ~8       The first 8 chars in the sender's username
   ~y       The time and date in RFC-822 format
   ~d       A random integer, expressed as 4 hex digits
   ~q       Y if this message is a BCC, N otherwise
   ~%name%  The value of the environment variable %name%.
   ~p       The user's personal name preference
   ~x       The name.ext ONLY of the container file (no path)
   ~a       The directory from which PMail was run (or base directory)
   ~h       The current user's home mailbox location
   ~w       The current user's new mail location
   ~~       A single tilde character.

Example: Assume that you have defined the gateway output command

   mygate ~c ~8 sys:mail/~b

And a user called DAVID, whose bindery ID is 4000001 sends a 
message which PMail stores in c:\temp\119944.tmp. When PMail 
invokes your gateway, the command line will be as follows:

      mygate c:\temp\119944.tmp DAVID sys:mail/4000001

In the following description of the Gateway Definition screen, 
fields marked with an * will support command substitution. Command 
substitution is also possible in the "Home mailbox" and "New 
mailbox" fields of PMail's standalone configuration screen.


Gateway definition fields
-------------------------

Gateway name:  This is the name by which users will know this 
gateway. It should follow legal NetWare naming rules, and cannot 
contain spaces.

Users will access the gateway using NetWare usercode syntax so, 
say you call your gateway HONG_KONG, and a user wants to mail 
to someone called J_JONES at the gateway, they would enter the 
address as HONG_KONG/J_JONES.

*New mail path:  This is either a full path to a location where 
PMail is to find new mail, or else the name of a program to run 
when checking for new mail. You can use command substitution 
in this string to construct complex paths.  note that PMail will 
assume that ALL mail matching the search mask is for the current 
user - it will not parse messages to determine the recipient. 
If your transport places new mail in the mail directory each 
user has in SYS:MAIL, using a .CNM file extension, then you do 
not need to enter anything in this field. Note that if you have 
a gateway which writes messages into the user's NetWare directory 
in SYS:MAIL using an extension other than .CNM, you can enter 
a search path here using this command substitution: SYS:MAIL/~b 
(See the section on command substitutions for more on this).

Is ^ a program to run?  Enter 'Y' if "New mail path" is a program 
 name rather than a directory name. Gateways which require a 
program  to be run to retrieve new mail will not be polled periodically 
- rather, the "check for New mail" option will remain permanently 
on the main menu, and the program can only be run when that option 
is selected.

*New mail search mask:  This is a DOS filename pattern which 
PMail is to use when searching the New mail path for new mail. 
New mail messages will be rewritten in the user's home mailbox 
using the normal PMail naming convention prior to reading, but 
they need not be in this format as written by the gateway.

*Outgoing mail path:  The name of the directory in which PMail 
should create outgoing mail messages. Again, command substitution 
(described above) can be used in this string for specialised 
processing.

*Run for outgoing mail:  If you enter a program name in this 
field,  PMail will run it every time it sends new mail to the 
gateway. The program must leave  the screen in the condition 
it found it (ie, if it writes to the screen, it must do so using 
non-destructive windows). This field is the one which will normally 
benefit the most from the use of command substitution (see above). 
By embedding escape keys in this string, you can construct extremely 
complex command lines. Usually, this field will refer to a "glue" 
program you have written to interface with the gateway: the actual 
invocation of the gateway is intended to be user-activated via 
choices in the SENDER.PM file.

*Filename format:  This field allows you some control over the 
filenames PMail will use when creating outgoing messages. The 
~d command substitution (random integer value) is often very 
useful in this field.

Run to validate address:  You can provide a program which PMail 
will call to validate that an address is correct. If you do so, 
enter it in this field. Unlike other command strings, command 
substitution is not possible with this field  the only parameter 
passed on the  command line is the address to validate. Your 
program must not disturb the screen, and must return 0 if the 
address is invalid, or non-zero if the address is OK.  If nothing 
is entered in this field, no attempt will be made to validate 
addresses.

*Reply address format:  This field allows you control how PMail 
will construct the "From" address in outgoing messages. You can 
use command substitution in this field.  

   Example: entering ~8@home.otago.ac.nz (~p)
   will cause the from field of messages from user david to read 
   david@home.otago.ac.nz (David Harris).

Accepts SMTP addresses:  If your gateway accepts messages using 
standard internet address formats, set this flag to 'Y'. If Charon 
is not installed on your system and a user enters a standard 
internet address, PMail will examine all available gateways, 
and will pass the message to the first with this flag set. This 
allows users to send internet mail using normal addressing, rather 
than having to send it specifically via a gateway using the SERVER/ADDRESS 
format.

Simple message headers:  PMail can write messages with extra 
preparsed address information at the beginning of the message in
either of two formats:

1: Simple message headers is the original form provided by PMail.
   It is not particularly effective and is only provided for
   backwards compatibility.

   The simple header information is line-based, using line number
   as a key. Gateways which read simple message headers must read
   until a totally blank line is encountered, then send the remainder
   of the message, which will be normally formatted. At present, two
   lines are defined in the simple headers, although others may
   be added in future:

    * Line 1: The recipient of this message (not the same as
      the To: field)
    * Line 2: Contains 'Y' if this message has attachments.

   Lines without values will contain a single space. Addresses are 
   already parsed. Since the format is intended to be extensible, 
   gateways which understand simple headers must ignore lines they 
   are not written to use, and must read until the blank line.

2: 'Glue' headers are an extension of simple headers; they are
   essentially a variant of the format PMail uses for Charon and
   Mercury with a little more information. The first line of the
   message is the signature "$$ " followed by the "from" address
   of the sender. Each subsequent line lists all the addressees
   to which this message should be sent, with a single character
   code at the start of the line indicating whether the address
   is for someone in the "to" field (T), the CC field (C) or the
   BCC field (B). The code is followed by exactly one space then
   the address. The glue headers end with a blank line and are
   followed by the message in canonical RFC822 format. Gateways
   designed to work with glue headers MUST IGNORE a line which
   starts with an unrecognized code character: this allows the
   format to grow. The PMPOP POP3 gateway for PMail v3.0 expects
   to see messages in glue header format.

UUencode attachments:  If 'Y', then PMail will generate a separate 
message for each attachment, and will uuencode the attachment 
into the message. If 'N', a file with the same name as the message 
but the extension '.ATT' will be written into the outgoing mail 
directory, along with the attachments. The .ATT file will contain 
the names of the attachments to the message, one per line.

   (PMail currently ONLY supports uuencoded attachments).

Burst messages?  If 'Y', then PMail will create one message for 
every address sent to: it is up to your gateway process to use 
the ~t command substitution to ensure that delivery is correct, 
since you generally will not be able to tell from the message's 
headers who a particular copy should be sent to. If 'N', PMail 
assumes that your gateway can parse the message for address data, 
and will write all the addresses into one message, using standard 
RFC-822 folding and header rules. The exception to this is messages 
with a BCC header: this will generate two envelopes, one with 
the BCC field, the other without. Your process can determine 
which is the BCC delivery using the ~q command substitution.

Force all mail through:  If you set this field to 'Y', then PMail
will pass all mail irrespective of addressing to the gateway for
processing. This effectively disables PMail's support for all other
transports in the system.


Gateways and BCC:
----------------

Messages with BCC (Blind Carbon Copy) recipients present special 
problems to gateways, since the same message ends up being processed 
twice - once with no BCC header, then again as a separate job 
containing the BCC header. PMail can indicate to the gateway 
process that a message needs BCC processing (using the ~q command 
substitution), but it is up to the gateway process to ensure 
that the BCC field is properly handled, and that the message 
is correctly forwarded. If your gateway does not handle BCC as 
a special case, we recommend that you do NOT use BCC fields.


Altering the Main menu - PMail 3.0 and later
--------------------------------------------

Under PMail 3.0 and later, options are added to the "Send Message"
and "Check New mail" menu items via a resource file called
PM-MENU.RSC. A heavily-commented sample for this file is provided
with the PMail 3.0 distribution - please examine it for further
details.


Altering the Main menu - PMail 2.35 and earlier
-----------------------------------------------

Pegasus Mail v2.35 and earlier allow you to add sub-choices to 
two of the options on the main menu- "Check for New mail" and 
"Send a mail message". The addition is done via a text file called 
SENDER.PM, which must be stored in the same directory as PMAIL.EXE. 
This file contains sets of 5 lines, each set defining one sub-choice. 
Blank lines and lines beginning with a semi-colon (';') are treated 
as comments and are ignored. The lines within each set have the 
following meanings:

*	Line 1: Either N if this entry is to be added to the New Mail 
submenu, or S if it is for the Send message submenu.

*	Line 2: The text to show in the submenu

*	Line 3: Pegasus Mail will create a temporary filename which 
can be passed to the command you specify on the command line. 
If this field is Y, then PMail will look for the file when the 
command returns: if the file exists and is longer than 0 bytes, 
PMail will parse it as a message and mail it normally. This allows 
you to create alternative message entry screens. Note that if 
you use this option, the file must contain a properly-formatted 
RFC-822 message on return. Attachments cannot currently be specified 
in this file.

*	Line 4: Enter Y on this line if PMail should save its screen 
before invoking the command, and restore it when the command 
returns. If N, then PMail assumes that the command either does 
no screen output, or that it does it non-destructively.

*	Line 5: Enter the command PMail should invoke on this line. 
All command substitutions (see above) are possible here. The 
maximum length of an entry on this line is 80 characters, although 
the command line may be up to 128 characters in length after 
command substitution. To invoke the usual built-in function (ie, 
either Check for New Mail or Send a Message), enter a single 
colon (':') on this line. The command you enter here may be an 
MS-DOS batch file or an executable image.


A Sample Implementation - PMail and Waffle.
-------------------------------------------

Waffle is a particularly good Bulletin-Board System which is 
widely distributed as Shareware on the Internet and on numerous 
public services. Among its features is a solid implementation 
of uucico, the UNIX copy-in - copy-out routine used to make uucp 
transfers. Remember that Waffle is a Shareware program: we urge 
you to send in the shareware license for Waffle if you use any 
part of it - the program is well worth it, and the author deserves 
support.

PMail can be quite easily interfaced with Waffle, providing a 
quite functional standalone mail facility via uucp. One small 
"glue" program is required - the source for this is included 
on the PMail distribution diskette as an example of how gateways 
can be implemented. The glue program was written by Brendan Murray, 
Systems Manager at the University of Otago. Brendan has kindly 
made the source freely available and modifiable without charge 
or restriction. Both the glue code and this example assume that 
you have a properly-configured copy of Waffle on your system.

Essentially, PMail creates a temporary file, then passes it to 
the glue program, using a number of command substitutions to 
minimise the parsing the program has to do. The glue code then 
parses Waffle's static configuration file and creates appropriate 
mail files in the right place for uucico and uuxqt. Two options 
are added to the main menu to allow the user to choose when to 
invoke uucico to process outgoing mail, and receive incoming 
mail.

A sample user-defined gateway definition for Waffle is as follows:

Gateway name:              WAFFLE
New mail path:             c:\mailbox\~8
Is ^ a program to run?:    N
New mail search mask:      ~8.*
Outgoing mail path:        c:\scratch\tmp
Run for outgoing mail:     c:\bin\filter ~n ~c ~t ~y
Filename format:           ~d~d.WOM
Run to validate address:	
Reply address format:      ~8@myhost.domain
Accepts SMTP addresses?:   Y
Simple message headers?:   N
UUencode attachments?:     Y
Burst messages?:           Y
Strip GW name?:            Y
Check new mail every x seconds.


Brendan's filter program locates Waffle's configuration file 
using the WAFFLE environment variable; it expects parameters 
on the command-line in the following order:

   1:	The name of the user sending the message
   2:	The name of the message container file
   3:	The To: field of the message
   4:	The time and date as an RFC-822 string



The SENDER.PM file for PMail using Waffle is as follows:

S
Regular mail message
N
N
:

S
Send all outgoing mail
N
Y
uucico

N
Read new mail messages
N
N
:

N
Check host for new mail
N
Y
uucico

