
Pmail 0.9
---------

Pmail is a command-line email transfer client based on the POP3 and SMTP 
protocols. The basic idea of pmail is to transfer mails online but to process 
messages offline so it could reduce the online time and costs. Pmail receives 
remote mails by POP3 protocol and saves them to local folder in the FromSPACE
form, which is a kind of messages composing form used by several standard 
UNIX programs such as mail/mailx. Pmail is not a message processor. But you 
can use quite a lot message processors like mailx, mailz, elm, mutt, pine and
any other MUAs if they can handle the FromSPACE message folder. Although it 
is assumed that all reply messages are collected in a local postpone message
folder, which are going to be delivered when online by SMTP procotol, you 
can also compose a message online, or transfer a file via the traditional 
shell pipe.

The main functions of pmail are:

*) multi-maildrops are supported.
   You can list several POP3 servers at 'fetch' option in the configure file.
   Pmail will connect these servers one by one and download mails.

*) Anti-spam remote message filter (experimental)
   You can set message filter in the configure file. Before downloading a 
   whole message, pmail should check the message head according to the filter
   regular. All messages that trigger the filter regular will be removed from,
   or kept in the server end. Those filter regulars could construct several
   different filter chains, and they are powered by regular express.

*) a custom POP3 client
   You can instruct pmail to access each server by different way. For example,
   it can just check some maildrops, or remove mails from some maildrops with-
   out downloading them.
   
*) external pipe
   You can preprocess a message via external pipe before delivering it, such
   as PGP or MMENCODE etc.

*) online message
   You can compose a message online. This idea is from the similar function
   of mailx. For example:

       pmail -s "hello" -b bcc@xxx.com sb@somewhere.com < somefile
           

Quick install
-------------

Extract the package then

./configure
make
make install



Configuration
-------------

There is a file named "pmailrc" in the distribution package. You can copy
it to your home directory and rename it to ".pmailrc", and then edit this 
config file. Read it carefully for information of options. I hope it could
self-explain. By the way, this configure file is not life-tied. Command
line options make it run well for most situation.



About FromSPACE form and PINE
-----------------------------

In message folder there are lines started with "From " between messages.
Pmail, and some other email softwares use it to separate and identify each
message in the folder. For example:

  From fents@ibiblio.org Wed Sep  6 01:07:27 2000
  From: Serena Fenton <fents@ibiblio.org>
  To: xuming@iname.com
  Date: Tue, 17 Oct 2000 08:36:00 -0400
  Subject: Re: Some trouble.

The first line "From fents@ibiblio.org Wed Sep  6 01:07:27 2000" is the start
point of this message. When pmail drops message, it will operate from this 
FromSPACE line and drop the body to xuming@iname.com in the name of 
fents@ibiblio.org.

Pine adopts FromSPACE form too. But it adds an 'anchor' message in the start
points of message folders. The typical form is:

  From MAILER-DAEMON Sat Feb 10 14:36:21 2001
  Date: 10 Feb 2001 14:36:21 +0800
  From: Mail System Internal Data <MAILER-DAEMON@xuming.homenet.xu>
  Subject: DON'T DELETE THIS MESSAGE -- FOLDER INTERNAL DATA
  Message-ID: <981786981@xuming.homenet.xu>
  X-IMAP: 0981786966 0000000150

  This text is part of the internal format of your mail folder, and is not
  a real message.  It is created automatically by the mail system software.
  If deleted, important folder data will be lost, and it will be re-created
  with the data reset to initial values.

Pmail now can recognize the PINE anchor by keyword 'From MAILER-DAEMON'. So
this message will keep untouched.


The message head in the postpone folder
---------------------------------------

The postpone folder adopts FromSPACE form too. These message heads influence
pmail:

    From:       sender address (option). the default option is "reply-to" in 
                the configure file.
    To:         receiver addresses. separate by comma (,).
    Cc:         carbon copy to addresses. just like 'To:' does.
    Bcc:        blind carbon copy addresses. This line should not drop out.
    X-behave:   Pmail special head, messages will be processed individually:
                pipe/unpipe   enable/disable external pipe.
		sign/unsign   enable/disable signature file.
		exhd/unexhd   enable/disable extra message heads.
		pure          equivalent to "unpipe,unsign,unexhd".

Other message heads will be forward directly.


About Anti-spam
---------------

Pmail have the ability of removing spam-like messages from server without
the entire downloading. It depends on the TOP command to check message heads.
When spam rule is trigged, pmail can remove this mail, keep it at server
or remind user. Although the TOP command is optional by RFC1725, it has been
supported by most POP3 servers.

By now pmail can check three characters of a message: message size, message
source and message subject. Message source includes 'from:', 'sender:' and
'reply-to:'. Pmail matches these head part by regular expression patterns.
According to the result of matching, you have six choices: remove message
when true matched, keep message in the server when true matched, ask user
when true matched, remove message when false matched, keep message in the
server when false matched, ask user when false matched. 

You must set up anti-spam rules in the configure file. Two steps are
required:

1. write filter rules.
2. aiming to individual server, enact choosed rules.

The filter rules are defined with 'spam' compound options in the configure
file. There are examples in this file. The typical format is:

spam {
  id:
  quota:
  from:
  subject:
  action:
}

An id is an identity of the class of filter rules. It's an arbitrary integer.
'Quota', 'from' and 'subject' are used to check messages. 'Action' is the
relative operation of filter results. There are six choices: true-delete, 
true-keep, true-ask, false-delete, false-keep, true-ask. You can use one of
'quota', 'from' and 'subject' as filter regular. More complex, they can be 
combined with AND logical. For example, if an anti-spam rule specifies 'from'
and 'quota' regulars, only when message comes from the 'from' address and
is larger than 'quota', it makes a TRUE result.

We usually need a lot of anti-spam regulars to cope with large numbers of
spam mails. Using 'id' in the anti-spam rule, several different rules can
be chained. 

    +------+    +------+    +------+    +------+
    | id=6 |--->| id=6 |--->| id=6 |--->| id=6 |---> ...
    |------|    |------|    |------|    |------|   
    |regula|    |regula|    |regula|    |regula|   
    | ...  |    | ...  |    | ...  |    | ...  |
    +------+    +------+    +------+    +------+
    
When any rule in the chain is trigged, the message should be bounced. You 
can choose several different chains according to different servers. Different
chains combine to a longer chain.

Writting rules and making chains is just the first step. Next we should enact
these chains aiming to speicified servers. In the 'fetch' option, the fourth
column is used to enact anti-spam chains. Putting 'n' there means no anti-spam 
filter required, otherwise chain id, same to the rule id, should be listed.
Pmail will check every messages and force them go through all nodes in these
chains before download, or other operating, them. For example, if these is
an option like this:

    fetch pop3.host.com:pop3:d:0,1,2,4:~/mbox:*:*

Pmail will create a anti-spam rule chain looking like this:

    +------+    +------+    +------+    +------+    +------+    +------+ 
    | id=0 |--->| id=0 |--->| id=1 |--->| id=2 |--->| id=2 |--->| id=4 |
    |------|    |------|    |------|    |------|    |------|    |------|    
    |regula|    |regula|    |regula|    |regula|    |regula|    |regula|    
    | ...  |    | ...  |    | ...  |    | ...  |    | ...  |    | ...  |    
    +------+    +------+    +------+    +------+    +------+    +------+    
    
And test every messages come from pop3.host.com.


About mailz
-----------

Mailz is an email user agency with a mailx(1) looking style. Most commands
derive from mailx(1) but enhanced. Mailz can handle several message folders
concurrently and supports history command, address book, external pipe,
HZ decoder, and a hacker version MIME decoder. Mailz shares the same configure
file with pmail. Though mailz is not as friendly as curse-based full-screen
MUA like mutt, it's quick in my 486 computer.


TODO
----

*) supports IMAP protocol
*) supports sendmail authentication


Copyright
---------

See the file "COPYRIGHT" inside this package.


Examples
--------

pmail

If the "default" item set to "pop3,sbox" in the option file, pmail should
connect to the specified POP3 server by "pop3host" first, then download the 
mails (or other action). After that it connects to the specified SMTP server
by "smtp" item in the option file, sends the messages stored in the outgoing
mailbox instructed by "postpone" option.

pmail -s "send file" -b bcc-addr@somewhat.net noname@hello.net < somefile

Transfering a file named "somefile" to "noname@hello.net" and blind carbon 
copy to "bcc-addr@somewhat.net" with the subject "send file". The SMTP server
should be specified in the option file.

pmail -dd -h pop3.noname.com -f localbox

Retrieval mails from the server of pop3.noname.com and save them in the file
of localbox, then remove them from server.

pmail -o -h smtp.noname.com -f postpone

Forward mails stored in the postpone file via the SMTP server smtp.noname.com

pmail -p

Listing the message head in the postponed folder.



