            POPwatch v2.70 (c)1997,98 Gary A. Priest
            ----------------------------------------

Welcome to POPwatch for the Atari ST/STE/TT/Falcon and compatibles.

POPwatch is a POP3 mailbox tool for use with STiK or STinG and a
POP3 mailbox.

Using POPwatch, you can see at a glance how much mail is in your
POP3 mailbox, delete any unwanted emails, view part of the email 
without downloading the whole thing, or download selected emails onto 
your Atari for use in your current mail client. 
Currently Oasis2, NEWSie, and NOS formats are supported. NOS format is 
used by Okami 1.29 and above, and Oasis1.

POPwatch also has a Kill File facility for the automatic deleting of 
emails that meet a specified criteria.

Thus it is now possible check your email *before* downloading it, and 
without having to make a connection via NOS or ICE. You can now 
download your email whilst browsing the web, for instance.

It is not meant to be a full mail client, ie. you cannot edit emails, 
post replies etc. It is meant to complement your existing email client 
and offers features not found in them.

New to version 2 is the ability to also send email from Oasis2, 
NEWSie, and NOS, Okami or Oasis1.

Also new in version 2 is the ability for POPwatch to automatically 
inform you of any new email as and when it arrives (as long as you are 
currently connected to you ISP via STiK).
 
This version of POPwatch is CHARITY WARE. See details at the end of
this document.


CONFIGURING POPWATCH
--------------------

Edit User Preferences.
----------------------
This is where you define such things as the POP3 mail server, account 
name and password. These fields should be self explanatory.

Password is not mandatory, and if not specified, POPwatch will request 
the entry of a password when attempting to connect to the POP3 server.

SMTP Server
-----------
This need only be defined if you wish to send email via POPwatch.

Retrieval Format
----------------
POPwatch can retrieve email in one of three formats;
Oasis2, NEWSie, and NOS (also used by Oasis1.xx and Okami).
The NOS format is more formally known as the Berkeley Unix Mailbox
format and can be imported into any Email client that supports it.
eg. this could be useful for importing into a PC client such as 
Turnpike or Agent. Both of these support this format.

Select which one applies to your existing email client.

Path
----
This is the path that the email should be retrieved into.

eg. Oasis2 \OASIS2\INCOMING\
    NEWSie \NEWSIE\MAIL\
    NOS    \NOS\SPOOL\MAIL\ or OASIS\SPOOL\MAIL\

Leave Mail on Server
--------------------
If set to YES, POPwatch will leave the email on the POP3 server after 
it has retrieved it.

If set to NO, POPwatch will DELETE the email from the POP3 server 
after it has retrieved it.

Until you are familiar with the operation of POPwatch, I suggest that 
you leave this set to YES, and manually delete the emails. Just in 
case.

Send Format
----------------
POPwatch can send email from one of three formats;
Oasis2, NEWSie, and NOS (also used by Oasis1.xx and Okami)
Select which one applies to your existing email client.

Path
----
This is the path that the outgoing email is stored.

eg. Oasis2 \OASIS2\OUTCOMING\
    NEWSie \NEWSIE\MAIL\
    NOS    \NOS\SPOOL\MQUEUE\ or OASIS\SPOOL\MQUEUE\

Signature
---------
This is only for use if you are sending email from NEWSie. 
Simply specify the signature file you wish to use and POPwatch will 
append it to each email as it is sent.
Oasis2 and NOS/Oasis1.xx do this automatically and hence this is not 
required for them.


Save User Preferences
---------------------
This saves the current user preferences. You can choose the filename 
(although it should end in .prf). Thus you can have gary.prf for 
Gary's email account, and fred.prf for Fred's email account.
Or one for retrieving into NEWSie, and one for Oasis2 etc.


Load User Preferences
---------------------
This loads a user preference file. Obvious really :)


Program Preferences
-------------------
Program Preferences allows you to set various options that are not 
user specific, but program specific.

Edit General Preferences
------------------------

Default User
------------
Clicking on this field will allow you to select whichever user 
preference file you wish POPwatch to load in when it starts up.
User preference files are named *.prf

Multitasking
------------
POPwatch can run in either multitasking or non-multitasking mode.

In multitasking mode, POPwatch checks for window events and allows 
other programs to have processor time (by relinquishing processor 
time via appl_yield). Ideal for multitasking operating systems such as 
MagiC. 

In non-multitasking mode, the program does not check for window events
etc. Thus it can spend all it's time downloading data (should be faster).
Ideal where multitasking is not important but speed is.

Mail Logging
------------
If turned on, then POPwatch will create a log file of all emails 
either sent or received in OUT.LOG and IN.LOG.
The log contains details such as the from and to authors, date, 
subject etc.

Warn if NEWSie Active
---------------------
If POPwatch finds that NEWSie is running when you try and 
retrieve/send email then POPwatch will display a warning telling you 
to close you NEWSie In Box window. This window MUST be closed before 
retrieving any email via POPwatch into NEWSie (else the email is 
effectively lost (See NEWSIE.TXT)).
This can be turned off it annoys you (but at your own risk).

Check for new mail every n minutes
----------------------------------
POPwatch can now automatically check for any new email on the POP3 
server every n minutes (whilst you are connected to you ISP via STiK).
If new email is found then POPwatch displays a small window saying 
how many new emails exist and you have the option to ignore or connect 
now and display them.
Please also see the section on Check for Carrier Detect.

If the number of minutes is set to 0 then this function is disabled.

Retrieval Buffer Size
---------------------
POPwatch now buffers receiving of emails to improve the speed of
retrieval.
Instead of writing each line to disk as it is retrieved, POPwatch now 
stores them in memory and only writes to disk when the buffer is full 
or the end of the email is reached.
This field defines the size of the buffer in kilobytes.
The default size is 8K. I normally have it set to 300K, but if you 
regularly receive very large emails then set the buffer to something 
nearer their size to benefit most.

Check for Carrier Detect
------------------------
STiK will hang if trying to connect to a mail server and not on-line 
which causes a big problem for POPwatch's autocheck facility.
To get around this you can have POPwatch check for carrier_detect 
before trying to connect. This is what previous versions of POPwatch 
have always done and this relies on you having CDVALID=1 or TRUE in 
your STiK configs.

This is a bug in STiK and does not occur in GlueSTiK or STiNG, both of 
which do not actually support the carrier_detect function anyway.

This option *must* be deselected if you are using STiNG or GlueSTiK, 
otherwise POPwatch will not be able to autocheck your mailbox.

Display header plus xxx lines
-----------------------------
When double clicking on an email, POPwatch will display part of that
email. ie. the header and so many lines of the body.
The number of lines is defined here and defaults to 20.


Edit Rejection Preferences
--------------------------
Preferences that affect the way POPwatch can reject certain emails 
can be maintained here. They are saved as part of the Program 
Preferences.

Delete Email After Rejecting
----------------------------
If this is selected, POPwatch will automatically DELETE the selected 
email AFTER a Rejection DSN has been sent.

Automatically Reject Killed Email
---------------------------------
If this is selected, any emails that are automatically killed by POPwatch
upon connection to the POP3 server will also automatically have a Rejection
DSN sent to the originator of each email. Thus not only does POPwatch 
kill the email for you it also tries to convince the originator to not 
send you anymore.

The Rejection DSN's are only sent when Disconnecting from the POP3 
server. Killed email is now only physically deleted upon disconnection from 
the POP3 server. This differs from versions below 2.30.

Automatically Add to Kill File
------------------------------
If this is selected, POPwatch will automatically add the originator 
(return-path) to it's KILL.TXT file. This ensures that once you have 
rejected an email from a particular person, any subsequent emails are 
automatically killed and/or rejected.


Save Program Preferences
------------------------
This saves the current settings from the Edit Program Preferences 
window.

It also saves the current positions of all POPwatch's windows.

It also save the status of the 'logging' menu option. Thus if logging 
is turned on when this option is taken, it will always be on in 
the future until you turn it off again and save program prefs again.


Edit Sound Preferences
----------------------
POPwatch can now play sounds samples after various events via a third 
party sample player such as NED Player or GEMJing.

All fields in this window are editable, but single clicking on them 
will bring up a file selector.

Holding down a SHIFT key whilst single clicking on a sample field will 
play that sample (assuming you have defined a player first).

Activate Sounds
---------------
The sounds will only be played if this button is selected.

Player
------
Tell POPwatch which player you are going to use. It must be able to 
accept a filename as a command line parameter.
If you know that the player supports VASTART then you should select 
the VASTART button (NED Player and GEMJing do).

Command
-------
Some sample players allow you to prefix the filename with commands to 
determine how the sample will be played. This field is where you can 
enter the commands needed. See the documentation that comes with the
player for details of this.

If using GEMJing, pass it a -q command and use VA_START.

If using NED Player, pass it a -w command and use VA_START.

Connect, Disconnect, etc.
-------------------------
You can define a separate sample per listed action. The sample will 
be played at the end of the event eg. Connect will play a sample once 
POPwatch has connected to the POP3 server and displayed the headers of 
all waiting email.


Save Sound Preferences
------------------------
This saves the current settings from the Edit Sound Preferences 
window.


USING POPWATCH
--------------

1. Connect to your ISP with STiK.

2. Run POPWATCH.PRG

3. Select 'Connect', and POPwatch will log on to the specified POP3 
   mail server and retrieve details of any mail that exists in the 
   specified account. The kill file will also be checked and any 
   emails that match kill criteria will be killed.

4. Now you can select multiple emails, and process them as follows:

   a) Delete them.
      They are only physically deleted from your POP3 account when
      you DISCONNECT, until then you can 'undelete' them using the
      menu option 'abandon deletes'.

   b) Retrieve them.
      The emails will be fetched from your POP3 mailbox and
      downloaded to your Atari in whichever format is specified in
      the current user preferences.
      If the 'Leave Mail on Server' setting in preferences is NOT set, 
      then the mail will be deleted from the server after successful
      downloading of the email.

5. Double clicking on a particular email, will retrieve the header and 
   first so many lines of that email (the number can be defined in 
   Program Preferences but defaults to 20), and display them in a window.
   This is useful if you just want to see *part* of the email, before 
   downloading it all or deleting it.
   
6. Disconnect from your Pop mailbox, using 'Disconnect'. Quitting the 
   program does this automatically.


ACCESSING THE RETRIEVED EMAIL
-----------------------------

Oasis2
------
Once retrieved, POPwatch creates the necessary MAIL.IN and MAIL.IDX 
files in the defined retrieval path ie. \OASIS2\INCOMING\
When you next run Oasis2 and select the PostBox menu option, Oasis2 
will automatically 'index' the retrieved mail just as if it had been 
downloaded using ICE.
Demon users will find the email is allocated to the correct user.
NON Demon users may not be so lucky because POPwatch has to rely on 
the 'To' address in the header field (which could be anything).
In this case, Oasis2 will ask you what you want to do with each email.

NEWSie
------
Once retrieved, POPwatch creates the necessary MAILxxxx.TXT and 
INBOX.MBX files in the defined retrieval path ie. \NEWSIE\MAIL\
When you next run NEWSie and open your IN Box, the emails are there 
ready and waiting.

NOS using Oasis1.xx
-------------------
Once retrieved, POPwatch creates the necessary nnnnnnnn.txt 
(where nnnnnnnn is the To: user) files in the defined retrieval path
ie. \SPOOL\MAIL\
When you next run Oasis1 and select the PostBox menu option, Oasis1 
will automatically 'index' the retrieved mail just as if it had been 
downloaded using NOS.
Demon users will find the email is allocated to the correct user.
NON Demon users may not be so lucky because POPwatch has to rely on 
the 'To' address in the header field (which could be anything).
In this case, it may be necessary to set up the relevant user in 
Oasis1, before being able to view the email.


SENDING EMAIL
-------------
If on start up POPwatch finds that you have outgoing email queued and 
waiting to be sent then it will ask you if you wish to send it.
If you choose to send it later you can do so by selecting the send 
button or menu option.

If whilst sending an email POPwatch receives an error from the SMTP 
server (such as unknown recipient) then a window will be displayed 
with details of the email and error. You can choose to cancel the 
whole sending of the email (and it won't go to any of the users) or 
simply ignore the user in question but still send it to the others.

Each send 'session' creates a send.log file which contains the 
conversation between POPwatch and the SMTP server. This will help you 
locate any errors if they occur.


SIGNATURE TEAR LINE
-------------------
It is quite common for people to prefix their signatures in email and 
news articles with a tear line of --<SP><CR><LF> ie. '-- '
NEWSie does not do this at this time, and previous versions of 
POPwatch used to prefix it automatically when sending the email.
This is no longer done, as of POPwatch 2.50.
If you wish your signature to be prefixed with the tear line, then you 
must manually edit your NEWSie signature file, and add it yourself.


USING THE ALIAS FILE
--------------------
NOS supports mail redirecting via use of a file called ALIAS.
POPwatch also uses this file if it exists, when retrieving email in the
NOS format. Unlike NOS, POPwatch has the following restrictions; it is 
limited to one aliasname mapping to one recipient thus multiple 
recipients are not handled, nor is mapping when sending email.

By using the ALIAS file it is possible to redirect email for 
non-existant users to a specific user, which can then easily be 
imported into Okami or Oasis1. This can be especially useful 
for mail coming from mailing lists, or junk mail.

A typical ALIAS file could look like:

* gary 			defines the default username
junk-email fred		any incoming email addressed to junk-email
			will be redirected to user fred
postmaster paul		any incoming email addressed to postmaster
			will be redirected to user paul

Defining the default user
-------------------------
You can specify a default delivery name in the ALIAS file. This 
name will be used if a match cannot be found in the ALIAS file. It
must be the very first line in the ALIAS file and of the format:
* name eg. * gary , will default all emails to unknown users to 
gary.txt.

Location of the ALIAS file
--------------------------
POPwatch looks for the ALIAS file in the same folder as POPWATCH.PRG
and if not found there then it will look in the old (pre 2.70 version)
location of retrieval path directory -2
eg. If you've set POPwatch's retrieval path to:
     E:\OASIS\SPOOL\INCOMING\
Then POPwatch will look for the ALIAS file in
     E:\OASIS\
If you don't have enough directories ie. E:\SPOOL\ or E:\SPOOL\INCOMING
then it will look in E:\


KILL FILE PROCESSING
--------------------
The Kill File allows POPwatch to automatically delete any emails that 
match specified criteria. eg. any with a subject containing '$' etc.
The emails will be flagged in the POPwatch window, with a 'K' as 
opposed to the normal deleted flag of 'X'. POPwatch will sound the 
system bell each time it kills an email as an audible warning.
Killed emails will also be shown in red instead of the usual black.

As with 'deletes' the kills are not made permanent until you 
disconnect, so you can still change your mind by using 'Abandon 
Deletes' from the menu *before* Disconnecting.

As of version 2.30, killed emails are not actually deleted from the 
POP3 server until you Disconnect from it.

The details of any emails killed are stored in a log file called 
KILL.LOG


MAINTAINING THE KILL FILE
-------------------------
POPwatch expects the kill file to be called KILL.TXT and looks for it 
in the same folder as POPWATCH.PRG.
This is a standard ASCII file (each line must end with a CRLF).
The file can either be maintained manually using a text editor, or 
via the 'Add to Kill File' menu option. This menu option will present 
the 'Add to Kill File' window. If no messages were selected when this 
option was taken, the fields will be blank. If multiple messages were 
selected at the time, then a window will be presented containing the 
details from each selected message in turn.
The Subject, From and To input fields can be altered and when you are 
happy that this is what you want added to the kill file, click Add.
NB. Empty strings will *not* be added to the kill file.

Each line in the file should consist of the following:

   <type><SPACE><string><CRLF>

where <type> is:

   F   Kill on the From: field
   T   Kill on the To: field
   S   Kill on the Subject: field

and <string> is the kill string which is *not* case sensitive.
   
eg. 

   S For Sale
   F stik@the-gap
   
Will kill any emails that contain the text 'For Sale' *anywhere* in the 
Subject line, and any emails that contain 'stik@the-gap' *anywhere* in 
the From field.

Make sure that you only define sensible kill strings. Defining one of 
's' would kill any emails that contain 's'. Not very clever or useful.
So take care when using this feature.


REJECTING AN EMAIL
------------------
As of version 2.30, POPwatch has a new feature to combat the unwanted 
nuisance of 'junk email'.

POPwatch can now reject unwanted emails, this can be done
automatically when using the Kill File option, or manually by 
selecting one or more email and taking the 'Reject' menu option.

When POPwatch rejects an email, what it actually does is send what is 
none as a Delivery Status Notification (DSN) to the originator of the 
email (as specified in the return-path: field in the email header).

This DSN looks exactly like the kind of automatic response that would 
be sent if your email address didn't exist, and should hopefully 
convince the originator of the message that you do not exist, and thus 
remove you from their mailing lists. Hopefully :)

To the origniator of the email, it simply looks as if their email has 
failed to reach you!!

Some junk mail claims that if you respond with a 'remove' message, you 
will be automatically removed from their lists. Many people suggest 
that this is not in fact the case, and that by replying to the email, 
you have shown that a) you read junk email, and b) your email address 
really does exist. In both cases they could well just send you more 
email. :(
By using POPwatch to reject the email instead, they have to assume 
that you haven't read their email, and that is because your email 
address doesn't exist!!

POPwatch can also be configured (in the Rejection Preferences 
window), to automatically send Rejection DSN's when killing email, to 
automatically add the originator of any manually rejected email to 
your kill file, and to automatically delete an email after it has been 
manually rejected.

Details of Rejected Email are stored in LOGS\REJECT.LOG


ESMTP SUPPORT
-------------
POPwatch now supports SMTP extensions. There are many different 
extensions but POPwatch at present only supports the SIZE extension
(RFC 1870). POPwatch will only attempt to use this extension if it 
determines that your SMTP server understands it. This is achieved by 
using the EHLO command instead of the HELO command (See RFC 1869).
If SIZE is returned then POPwatch will use the extension, else it will
function as before.


DEMON USERS
-----------
For users of Demon Internet's POP3 service, POPwatch uses the 
following extra facilities of this service:

a) multiple mailboxes. If you just want to see what mail is waiting 
   for sue@the-gap.demon.co.uk then prefix the host name with the user 
   name ie. in preferences, set account to sue@the-gap.
b) Use of *ENV. This is a Demon specific command and requests the SMTP 
   envelope of an email. This is much more specific than the use of 
   the header fields 'from' and 'to'. Thus your mail get's routed 
   to the correct user in Oasis2 and NOS.
c) Also by using the *ENV command, it is possible for POPwatch to 
   determine if an email message has been read (ie. retrieved, not just 
   the top 10 lines displayed). POPwatch will show any such messages 
   in blue (assuming that you are running in a resolution with more 
   than 4 colours), and will flag them with an 'R' beside the msg 
   number. Note that any such messages are automatically 
   deleted by Demon after 30 days, without sending a bounce 'not 
   received' message back to the originator.


PARAMETER PASSING VIA THE COMMAND LINE OR VA_START
--------------------------------------------------

Automated control of POPwatch can now be achieved by passing it 
parameters either via the normal command line or via VA_START.

The parameters can be:
    user profile filename (optional) ie. fred.prf

followed by:
    /c = connect
    /d = disconnect
    /r = retrieve all messages
    /s = send queued email
    /q = terminate POPwatch

eg.
    fred.prf /c /r /d /q
will load user profile fred.prf, connect, retrieve email, disconnect, 
and quit POPwatch.

    /s 
will use the default user profile, and send all queued email


VERBOSE DISPLAY
---------------
This window shows all conversation between POPwatch and the POP3/SMTP
servers, although actual email content will not be displayed.
This window can be set to open automatically, if it is open when 
General Preferences are saved.


THE HISTORY FILE
----------------
Every email message should contain a unique Message-Id: field (as 
defined in the RFC's).
When you use POPwatch to retrieve an email, it stores the message-id 
in \LOGS\HISTORY. This file can get quite large and should be deleted
whenever appropriate.

POPwatch can use the information in the history file to give a 
visible indication of whether or not an email on the POP3 server has 
already been retrieved.

If an email is found that has a message-id which is already in the 
HISTORY file (ie. POPwatch has already retrieved it), then a '*' 
is shown before the number in the 'Msg' column, and the line is 
displayed in dark green if running in a resolution with more than 4 
colours.

The creation and checking of the history file can be turned off if 
required from within the General Preferences window.


LOGGING CONVERSATION
--------------------
Turn on logging by selecting the 'Logging' menu item. This will then 
produce a log popwatch.log of the conversation with the server.
This may help me find any bugs if you have problems.


THE STATISTICS WINDOW
---------------------
This window shows various statistics that have been collected by 
POPwatch throughout it's everyday use.

It shows the number of times that POPwatch has been run, and also 
shows how many emails, and how much data, has been sent, retrieved, 
rejected, and killed.

It also shows how many message-id's are currently in the HISTORY file.
Every time POPwatch connects to the POP3 server, and downloads details 
of each mail stored there, it compares the message-id against all 
those in the HISTORY file. Thus the bigger the HISTORY file, the 
longer this process will take. As mentioned elsewhere in this manual, 
the HISTORY file should be regularly deleted to keep it's size down.


THE ABOUT WINDOW
----------------
Both the email address and the URL can be selected and copied to the 
GEM clipboard via (CTRL C or CTRL Insrt). This allows them to be 
pasted into any programs that support 'pasting' into their fields such 
as CAB. Saves all that typing!

For people who are really lazy, try double clicking on them.
A browser or mailer can be launched and passed a mailto: or http: url
eg. if you are ONLINE at the time, the web browser will go straight 
to my web site. Or in the case of the email address, you'll be all 
ready to start typing an email to me!
Two environment variables (BROWSER= & MAILER=) must be set up for this 
feature to work. These variables allow the program to know what 
programs to launch for web browsing and email.

Environment Variables
---------------------
BROWSER=C:\CAB\CAB.APP or whatever path points to your browser
MAILER=C:\CAB\CAB.APP or whatever path points to your email program (it 
must understand mailto: as a command line).

The variables will be searched for in this order:

1. STiK/STinG variables (defined within DEFAULT.CFG)
----------------------------------------------------
This is the preferred (and simplest) method.

Add the following lines to DEFAULT.CFG
BROWSER = C:\CAB\CAB.APP
MAILER = C:\CAB\CAB.APP

2. AES environment variables.
-----------------------------
Single TOS users can either get hold of programs such as GEMENV and 
SETENV or can use the file VARS.ENV.

Magic users should add the following lines to MAGX.INF
#_ENV BROWSER=C:\CAB\CAB.APP
#_ENV MAILER=C:\CAB\CAB.APP

MultiTOS or Geneva users should add the following lines to GEM.CNF
setenv BROWSER=C:\CAB\CAB.APP
setenv MAILER=C:\CAB\CAB.APP

3. VARS.ENV file.
-----------------
This file must exist in the same path as POPWATCH.PRG if you wish to 
use it.
Edit file VARS.ENV to point to whichever programs you wish to use.


BUBBLEGEM SUPPORT
-----------------
POPwatch supports the excellent BubbleGEM program by Thomas Much.
This program provides Windows95 style Help Bubbles when you right 
click on a particular control/field.
If BubbleGEM is running then right click on an entry field in POPwatch 
and you'll see a cute little help bubble appear!


CHARITY WARE
------------
In honour of Diana, Princess of Wales who so tragically passed away 
in the early hours of Sunday 31st August 1997, POPwatch is no longer 
FREEWARE! It is now CHARITY_WARE! If you like and use this program on 
a regular basis, then please make a contribution of the equivalent of 
10 UK Pounds to a worthy charity she would have approved of.

If you use and like POPwatch, then please drop me an email and tell me 
so. Without encouragement, POPwatch may not develop. So, even if it's 
just a one liner, please make the effort.


DISCLAIMER
----------
POPwatch is used at your own risk. I will not be held responsible for 
any damage caused either directly or indirectly from it's use, or the 
loss of any electronic data.


CREDITS
-------
Many thanks to the following people for their help and support in 
testing and translating POPwatch:

Lodovico Zanier - Italian Translation
Jo Vandeweghe   - French Translation
Mille Babic     - Swedish Translation


NEW VERSIONS
------------
The latest version of POPwatch can be found at my website:

http://www.the-gap.demon.co.uk/

   
Gary Priest 03/08/98
gary@the-gap.demon.co.uk
