docker-offlineimap/README.md

OfflineImap
===========

Description
-----------

OfflineIMAP is a tool to simplify your e-mail reading. With OfflineIMAP, you can
read the same mailbox from multiple computers. You get a current copy of your
messages on each computer, and changes you make one place will be visible on all
other systems. For instance, you can delete a message on your home computer, and
it will appear deleted on your work computer as well. OfflineIMAP is also useful
if you want to use a mail reader that does not have IMAP support, has poor IMAP
support, or does not provide disconnected operation. It's homepage at
http://offlineimap.org contains more information, source code, and online
documentation.

OfflineIMAP does not require additional python dependencies beyond python >=2.6
(although python-sqlite is strongly recommended).

OfflineIMAP is a Free Software project licensed under the GNU General Public
License version 2 (or later). You can download it for free, and you can modify
it. In fact, you are encouraged to contribute to OfflineIMAP.

Documentation
-------------

The documentation is included (in .rst format) in the `docs` directory.
Read it directly or generate nice html docs (python-sphinx needed) and/or
the man page (python-docutils needed) while being in the `docs` dir via:

    'make doc' (user docs), 'make man' (man page only) or 'make' (both)

    (`make html` will simply create html versions of all *.rst files in /docs)

The resulting user documentation will be in `docs/html`. The full user
docs are also at: http://docs.offlineimap.org. Please see there for
detailed information on how to install and configure OfflineImap.

Quick Start
===========

First, install OfflineIMAP. See `docs/INSTALL.rst` or read
<http://docs.offlineimap.org/en/latest/INSTALL.html>
(hint: `sudo python setup.py install`).

Second, set up your configuration file and run it! The distribution
includes offlineimap.conf.minimal (Debian users may find this at
`/usr/share/doc/offlineimap/examples/offlineimap.conf.minimal`) that
provides you with the bare minimum of setting up OfflineIMAP.  You can
simply copy this file into your home directory and name it
`.offlineimaprc`.  A command such as `cp offlineimap.conf.minimal
~/.offlineimaprc` will do it.  Or, if you prefer, you can just copy
this text to `~/.offlineimaprc`:

    [general]
    accounts = Test

    [Account Test]
    localrepository = Local
    remoterepository = Remote

    [Repository Local]
    type = Maildir
    localfolders = ~/Test

    [Repository Remote]
    type = IMAP
    remotehost = examplehost
    remoteuser = jgoerzen


Now, edit the `~/.offlineimaprc` file with your favorite editor.  All you have
to do is specify a directory for your folders to be in (on the `localfolders`
line), the host name of your IMAP server (on the `remotehost` line), and your
login name on the remote (on the `remoteuser` line).  That's it!

If you prefer to be compatible with the [XDG Base Directory
spec](http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html),
then substitute the above `~/.offlineimaprc` with
`$XDG_CONFIG_HOME/offlineimap/config` and don't forget to set
`XDG_CONFIG_HOME` properly if you want it to be different from
the default `$HOME/.config` for any reason.

To run OfflineIMAP, you just have to say `offlineimap` ― it will fire
up, ask you for a login password if necessary, synchronize your folders,
and exit.  See?

You can just throw away the rest of the finely-crafted, perfectly-honed user
manual!  Of course, if you want to see how you can make OfflineIMAP
FIVE TIMES FASTER FOR JUST $19.95 (err, well, $0), you have to read on our
full user documentation and peruse the sample offlineimap.conf (which
includes all available options) for further tweaks!


Mailing list & bug reporting
----------------------------

The user discussion, development and all exciting stuff take place in the
OfflineImap mailing list at
<http://lists.alioth.debian.org/mailman/listinfo/offlineimap-project>. You do not
need to subscribe to send emails.

Bugs, issues and contributions should be reported to the mailing list. Bugs can
also be reported in the issue tracker at
<https://github.com/OfflineIMAP/offlineimap/issues>.

Configuration Examples
======================

Here are some example configurations for various situations.  Please e-mail any
other examples you have that may be useful to me.


Multiple Accounts with Mutt
---------------------------

This example shows you how to set up OfflineIMAP to synchronize multiple
accounts with the mutt mail reader.

Start by creating a directory to hold your folders by running `mkdir ~/Mail`.
Then, in your `~/.offlineimaprc`, specify:

    accounts = Personal, Work


Make sure that you have both an `[Account Personal]` and an `[Account Work]`
section.  The local repository for each account must have different `localfolder`
path names.  Also, make sure to enable `[mbnames]`.

In each local repository section, write something like this:

    localfolders = ~/Mail/Personal


Finally, add these lines to your `~/.muttrc`:

    source ~/path-to-mbnames-muttrc-mailboxes
    folder-hook Personal set from="youremail@personal.com"
    folder-hook Work set from="youremail@work.com"
    set mbox_type=Maildir
    set folder=$HOME/Mail
    spoolfile=+Personal/INBOX


That's it!


UW-IMAPD and References
-----------------------

Some users with a UW-IMAPD server need to use OfflineIMAP's "reference" feature
to get at their mailboxes, specifying a reference of `~/Mail` or `#mh/`
depending on the configuration.  The below configuration from (originally from
docwhat@gerf.org) shows using a reference of Mail, a `nametrans` that strips the
leading `Mail/` off incoming folder names, and a `folderfilter` that limits the
folders synced to just three:

    [Account Gerf]
    localrepository = GerfLocal
    remoterepository = GerfRemote

    [Repository GerfLocal]
    type = Maildir
    localfolders = ~/Mail

    [Repository GerfRemote]
    type = IMAP
    remotehost = gerf.org
    ssl = yes
    remoteuser = docwhat
    reference = Mail
    # Trims off the preceeding Mail on all the folder names.
    nametrans = lambda foldername: \
    re.sub('^Mail/', '', foldername)
    # Yeah, you have to mention the Mail dir, even though it
    # would seem intuitive that reference would trim it.
    folderfilter = lambda foldername: foldername in [
    'Mail/INBOX',
    'Mail/list/zaurus-general',
    'Mail/list/zaurus-dev',
    ]
    maxconnections = 1
    holdconnectionopen = no


pythonfile Configuration File Option
-------------------------------------

You can have OfflineIMAP load up a Python file before evaluating the
configuration file options that are Python expressions.  This example is based
on one supplied by Tommi Virtanen for this feature.


In `~/.offlineimaprc`, he adds these options:

    [general]
    pythonfile=~/.offlineimap.py
    [Repository foo]
    foldersort=mycmp

Then, the `~/.offlineimap.py` file will contain:

    prioritized = ['INBOX', 'personal', 'announce', 'list']

    def mycmp(x, y):
        for prefix in prioritized:
            xsw = x.startswith(prefix)
            ysw = y.startswith(prefix)
            if xsw and ysw:
                return cmp(x, y)
            elif xsw:
                return -1
            elif ysw:
                return +1
        return cmp(x, y)

    def test_mycmp():
        import os, os.path
        folders=os.listdir(os.path.expanduser('~/data/mail/tv@hq.yok.utu.fi'))
        folders.sort(mycmp)
        print folders


This code snippet illustrates how the `foldersort` option can be customized with a
Python function from the `pythonfile` to always synchronize certain folders first.