Userguide
*********

Working with mail folders
=========================

Opening and creating mail folders
---------------------------------

There are four kinds of mail folders so far: Maildir, IMAP, POP3 and SMTP-Relay Each mail folder has a dedicated constructor named make-<foldertype>

Open an existing Maildir folder
...............................

     (defvar *inbox* (make-maildir-folder "/home/jsc/Mail/inbox/"))
     =>#<MAILDIR-FOLDER /home/jsc/Mail/inbox/

Note: the trailing slash in a Maildir folder's name is mandatory!

Create a new (empty) Maildir folder
...................................

     (defvar *outbox* (make-maildir-folder "/tmp/test-outbox/"
                                           :if-does-not-exist :create))
     =>#<MAILDIR-FOLDER /tmp/test-outbox/

Open an IMAP Folder
...................

     (defvar *imap* (make-imap-folder :host "imap.server.de"
     				 :username "user"
     				 :password "password"))
     =>#<IMAP-FOLDER imap://user!password@imap.server.de:110

The :create option for :if-does-not-exist does not work for IMAP folders.

Open a POP Folder
.................

     (defvar *pop3* (make-pop3-folder :host "pop3.server.de"
     				 :username "user"
     				 :password "password"))
     =>#<POP3-FOLDER pop3://user!password@pop3.server.de:110

The :create option for :if-does-not-exist does not work for POP3 folders.

Open a SMTP Relay Folder
........................

 -- function: make-smtp-relay-folder &key host port username password
     Opens a connection to the SMTP server HOST on the port given in PORT (defaults to 25). If USERNAME and PASSWORD is given then authenticated SMTP is used.

     (defvar *smtp* (make-smtp-relay-folder :host "smtp.arcor.de"
     				       :username "someone"
     				       :password "else"))

The :create option for :if-does-not-exist does not work for SMTP folders.

Access messages
---------------

Accessing messages works through proxy objects. A message object of a message fetched from a mailbox has its folder slot set to the folder it originates from.

To get a list of all accessible messages in a folder one can use the messages or the map-messages function.

 -- method: messages folder
     The result of this function is a list of accessible message objects in FOLDER.This objects can then get used to access the attributes and data of the messages.

 -- method: map-messages fn folder
     The result of this function is a list of accessible message objects in FOLDER.This objects can then get used to access the attributes and data of the messages. The function FN gets called for each message object one times. The order in which this occurs is undefined. The behaviour when accessing header-fields or any content of the message besides of the unique id is undefined too. The reason for this is that some folder implementations are not responsive while fetching messages so any request to them may fail. The purpose of FN is especially to provide progress feedback when fetching alot of message objects.

Both messages as well as map-messages should be implemented to do nothing more than to associate the message-objects with the unique ids of the messages in the folder. If the contents of the folder have not changed a cached list of message-objects can get returned.

     ;; All messages from the IMAP folder above
     (defvar *messages* (messages *imap*))

Copy Move and Delete Messages
-----------------------------

 -- function: copy-message message sink-folder
     This function writes a copy of MESSAGE into SINK-FOLDER.

 -- function: move-message message sink-folder
     This function moves MESSAGE into SINK-FOLDER. The default behaviour supported in the folder protocol is implemented through a copy and delete operation. Folder classes can override this behaviour by implementing move-message-using-folder

 -- function: delete-message message
     MESSAGE is deleted from its folder.

Sending Messages
----------------

The Common Lisp POP3 Server
===========================

Create an instance of the server
--------------------------------

Starting and stopping
---------------------

Configure authentication
------------------------

The Mail Reader
===============

Starting the Mail Reader
------------------------

Mail Reader Commands
--------------------