# $Id: README,v 1.10 2005/01/24 03:59:16 holger Exp $

README file for deletemail
==========================

OVERVIEW
--------

deletemail is a non-interactive tool for removing mail which is older than a
configurable number of days from one or more IMAP mailboxes.  By default, mail
which is not marked as seen on the server will not be deleted.  If, for
example, fetchmail is used for receiving mail from an IMAP server, deletemail
might be useful, since fetchmail deletes mail either immediately or not at
all.  Thus, you could use fetchmails "keep" option (so that fetchmail never
deletes anything) and let deletemail handle the removal of mail.  Currently,
the IMAP4 and IMAP4rev1 protocols are supported, optionally using SSL/TLS for
secure IMAP connections.


INSTALLATION
------------

In most cases, the following three commands should do (however, please see the
section on SSL support below):

  ./configure
  make
  make install

By default, this will install the deletemail binary and manual page to the
appropriate subdirectories of /usr/local.  Therefore, you'll normally need
superuser privileges when invoking "make install".  See the file INSTALL for
the gory details.


SSL SUPPORT
-----------

deletemail may be installed with or without SSL support for secure IMAP
connections.  In order to get SSL support, OpenSSL 0.9.7 or newer is required
(see http://www.OpenSSL.org/).  Most Linux distributions split OpenSSL into
two packages: The runtime library files and the header files.  The latter
package is often called "openssl-devel", "libssl-dev", or something like that.
BOTH packages are needed to install deletemail with SSL support.  By default,
if OpenSSL is installed to a standard location (like /usr or /usr/local/ssl),
deletemail will be built with SSL support, and without if not.  Alternatively,
"./configure --with-ssl" or "./configure --without-ssl" may be used to force
installation with or without SSL support.  If OpenSSL is installed to some
non-standard location, use "./configure --with-ssl=/path/to/ssl".


CONFIGURATION
-------------

In short, deletemail is configured via the file ~/.deletemailrc, which looks
like this:

  # ----------------------- 8< ----------------------------------------
  ACCOUNT # Toms INBOX on the ISPs server
    host: imap.provider.com # IMAP server
    user: tom               # username
    pass: h0lyPa55          # password
    days: 14                # delete mail which is older than two weeks
    ssl: yes                # use SSL for secure IMAP connections
  # ----------------------- 8< ----------------------------------------

To test your configuration, the command "deletemail -nv" could be used.  If
everything looks fine, it probably makes sense to call deletemail via cron(8).
By using the following crontab(5) entry, deletemail would be called once an
hour (at twenty past):

  20 * * * * /usr/local/bin/deletemail -q

Use "crontab -e" to add the entry.


DOCUMENTATION
-------------

Detailed information regarding the build and installation process can be found
in the file INSTALL.  For configuration and usage documentation, please see
the deletemail(1) manual page.  "deletemail -h" spits out a short summary of
the available command line options.  For each release, important feature and
bugfix additions are listed in the file NEWS.  Features which are planned for
future releases are added to the file TODO.  Copyright and license information
can be found at the top of each source code file and in the file COPYING.


PORTABILITY
-----------

deletemail is tested on Solaris, IRIX, FreeBSD, NetBSD, OpenBSD, OS X,
NeXTStep and Linux and should run on any recent UNIX OS.  Of course, an ANSI C
compiler is required in order to build the binary.  Compiling deletemail is
tested with GCC 2.5.8, 2.95.4, 3.3.3 and 3.4.2 on various operating systems,
Sun Forte C 6 Update 2 on Solaris 9 and SGI MIPSpro 7.4.2 on IRIX 6.5.24f.


FEEDBACK
--------

Please let me know if you have any comments or bug reports regarding
deletemail.  If you encounter problems, please include the output of
"deletemail -nvv".


AUTHOR
------

Holger Weiss <holger@jhweiss.de>
