299 lines
10 KiB
Plaintext
299 lines
10 KiB
Plaintext
OfflineIMAP
|
|
Copyright (C) 2002 John Goerzen <jgoerzen@complete.org>
|
|
This software comes with ABSOLUTELY NO WARRANTY; see the file
|
|
COPYING for details. This is free software, and you are welcome
|
|
to distribute it under the conditions laid out in COPYING.
|
|
|
|
gopher://quux.org/1/devel/offlineimap
|
|
http://quux.org/devel/offlineimap
|
|
|
|
==================================================
|
|
Welcome
|
|
==================================================
|
|
|
|
OfflineIMAP is a tool to simplify your e-mail reading. With
|
|
OfflimeIMAP, you can:
|
|
|
|
* Read the same mailbox from multiple computers, and have your
|
|
changes (deletions, etc.) be automatically reflected on
|
|
all computers
|
|
|
|
* Use various mail clients to read a single mail box
|
|
|
|
* Read mail while offline (on a laptop) and have all changes
|
|
synchronized when you get connected again
|
|
|
|
* Read IMAP mail with mail readers that do not support IMAP
|
|
|
|
* Use SSL (secure connections) to read IMAP mail even if your reader
|
|
doesn't support SSL
|
|
|
|
* Synchronize your mail using a completely safe and fault-tolerant
|
|
algorithm. (At least I think it is!)
|
|
|
|
* Customize which mailboxes to synchronize with regular expressions
|
|
or lists.
|
|
|
|
* Synchronize your mail two to four times faster than with other tools
|
|
or other mail readers' internal IMAP support.
|
|
|
|
In short, OfflineIMAP is a tool to let you read mail how YOU want to.
|
|
|
|
==================================================
|
|
Requirements
|
|
==================================================
|
|
|
|
To use OfflineIMAP, you must:
|
|
|
|
1. Have your mail delivered to a server that supports IMAP
|
|
|
|
2. Have Python 2.2 or above installed
|
|
|
|
3. Have a mail reader that supports Maildirs (most modern ones do)
|
|
|
|
These requirements are easy to meet, and most people will have met
|
|
them already without even being aware of it.
|
|
|
|
If you do not have Python already, check your operating system vendor
|
|
or download it from http://www.python.org/
|
|
|
|
==================================================
|
|
Installation
|
|
==================================================
|
|
|
|
Basic installation for a single user requires only these steps:
|
|
|
|
1. Copy offlineimap.conf to ~/.offlineimaprc and edit that file
|
|
for your accounts. Full instructions are in it.
|
|
|
|
2. Make the directory that you will store your folders in.
|
|
(~/Test in the example)
|
|
|
|
You can then just run "python2.2 offlineimap.py" to synchronize your
|
|
mail.
|
|
|
|
------------------------------
|
|
Systemwide
|
|
|
|
If you wish to install OfflineIMAP for all users on your system:
|
|
|
|
1. Either install the Debian package or run "python2.2 setup.py" and
|
|
follow the prompts
|
|
|
|
2. Advise users to perform steps 1 and 2 above
|
|
|
|
3. Run OfflineIMAP by typing "offlineimap"
|
|
|
|
That's it!
|
|
|
|
==================================================
|
|
Frequently Asked Questions
|
|
==================================================
|
|
|
|
Q. I get a message saying "UID validity problem for folder; skipping".
|
|
What does this mean and how do I fix it?
|
|
|
|
A. IMAP servers use a unique ID (UID) to refer to a specific message.
|
|
This number is guaranteed to be unique to a particular message
|
|
FOREVER. No other message in the same folder will ever get the same
|
|
UID. UIDs are an integral part of OfflineIMAP's synchronization
|
|
scheme; they are used to match up messages on your computer to
|
|
messages on the server.
|
|
|
|
Sometimes, the UIDs on the server might get reset. Usually this will
|
|
happen if you delete and then recreate a folder. When you create a
|
|
folder, the server will often start the UID back from 1. But
|
|
OfflineIMAP might still have the UIDs from the previous folder by the
|
|
same name stored. OfflineIMAP will detect this condition and skip the
|
|
folder. This is GOOD, because it prevents data loss.
|
|
|
|
You can fix it by removing your local folder and cache data. For
|
|
instance, if your folders are under ~/Folders and the folder with the
|
|
problem is INBOX, you'd type this:
|
|
|
|
rm -r ~/Folders/INBOX
|
|
rm ~/.offlineimap/AccountName/INBOX
|
|
|
|
(replacing AccountName with the account name as specified in
|
|
~/.offlineimaprc)
|
|
|
|
Next time you run OfflineIMAP, it will re-download the folder with the
|
|
new UIDs. Note that the procedure specified above will lose any local
|
|
changes made to the folder.
|
|
|
|
Some IMAP servers are broken and do not support UIDs properly. If you
|
|
continue to get this error for all your folders even after performing
|
|
the above procedure, it is likely that your IMAP server falls into
|
|
this category. OfflineIMAP is incompatible with such servers. Using
|
|
OfflineIMAP with them will not destroy any mail, but at the same time,
|
|
it will not actually synchronize it either. (OfflineIMAP will detect
|
|
this condition and abort prior to synchronization)
|
|
|
|
--------------------------------------------------
|
|
|
|
Q. What platforms does OfflineIMAP run on?
|
|
|
|
A. It should run on most platforms supported by Python, which are
|
|
quite a few.
|
|
|
|
--------------------------------------------------
|
|
|
|
Q. I'm using Mutt. Other IMAP synchronization programs require me to
|
|
"set maildir_trash=yes". Do I need to do that with OfflineIMAP?
|
|
|
|
A. No. OfflineIMAP is smart enough to figure out message deletion
|
|
without this extra crutch. You'll get the best results if you don't
|
|
use that setting, in fact.
|
|
|
|
--------------------------------------------------
|
|
|
|
Q. How do I specify the names of my folders?
|
|
|
|
A. You do not need to. OfflineIMAP is smart enough to automatically
|
|
figure out what folders are present on the IMAP server and synchronize
|
|
them.
|
|
|
|
--------------------------------------------------
|
|
|
|
Q. How can I prevent certain folders from being synced?
|
|
|
|
A. This feature will be introduced in a future version of OfflineIMAP.
|
|
|
|
--------------------------------------------------
|
|
|
|
Q. How can I add or delete a folder?
|
|
|
|
A. OfflineIMAP does not currently provide this feature.
|
|
|
|
--------------------------------------------------
|
|
|
|
Q. Are there any specific warnings or things I should be aware of
|
|
before using OfflineIMAP?
|
|
|
|
A. Yes. OfflineIMAP does a two-way synchronization. That is, if you
|
|
make a change to the mail on the server, it will be propogated to your
|
|
local copy, and vise-versa. Some people might think that it would be
|
|
wise to just delete all their local mail folders periodically. If you
|
|
do this with OfflineIMAP, remember to also remove your local status
|
|
cache (~/.offlineimap by default). Otherwise, OfflineIMAP will take
|
|
this as an intentional deletion of many messages and will interpret
|
|
your action as requesting them to be deleted from the server as well.
|
|
(If you don't understand this, don't worry; you probably won't
|
|
encounter this situation)
|
|
|
|
--------------------------------------------------
|
|
|
|
Q. What's thie Mailbox name recorder (mbnames) thing all about?
|
|
|
|
A. The Mutt mail reader is not capable of automatically determining
|
|
the names of your mailboxes. OfflineIMAP can help it (or many other)
|
|
programs out be writing these names out in a format you specify. See
|
|
the example offlineimap.conf file for details.
|
|
|
|
--------------------------------------------------
|
|
|
|
Q. Can I synchronize multiple accounts with OfflineIMAP?
|
|
|
|
A. Sure. Just name them all in the accounts line in the general
|
|
section of the config file, and add a per-account section for each one.
|
|
|
|
--------------------------------------------------
|
|
|
|
Q. Do you support POP?
|
|
|
|
A. No. POP is not robust enough to do a completely reliable
|
|
multi-machine synchronization like OfflineIMAP can do. OfflineIMAP
|
|
will not support it.
|
|
|
|
--------------------------------------------------
|
|
|
|
Q. Do you support mailbox formats other than Maildir?
|
|
|
|
A. Not at present. There is no technical reason not to; just no
|
|
demand yet. Maildir is a superior format anyway.
|
|
|
|
--------------------------------------------------
|
|
|
|
Q. [technical] Why are your Maildir message filenames so huge?
|
|
|
|
A. OfflineIMAP has two relevant principles: 1) never modifying your
|
|
messages in any way and 2) ensuring 100% reliable synchronizations.
|
|
In order to do a reliable sync, OfflineIMAP must have a way to
|
|
uniquely identify each e-mail. Three pieces of information are
|
|
required to do this: your account name, the folder name, and the
|
|
message UID. The account name can be calculated from the path in
|
|
which your messages are. The folder name can usually be as well, BUT
|
|
some mail clients move messages between folders by simply moving the
|
|
file, leaving the name intact.
|
|
|
|
So, OfflineIMAP must store both a UID folder ID. The folder ID is
|
|
necessary so OfflineIMAP can detect a message moved to a different
|
|
folder. OfflineIMAP stores the UID (U= number) and an md5sum of the
|
|
foldername (FMD5= number) to facilitate this.
|
|
|
|
--------------------------------------------------
|
|
|
|
Q. Can you provide an example of using OfflineIMAP with Mutt and
|
|
multiple accounts?
|
|
|
|
A. Sure. I set it up to have a single Mail directory with additional
|
|
directories under that for each account. So, mkdir ~/Mail. Then,
|
|
in your ~/.offlineimaprc:
|
|
|
|
Set "accounts = Personal, Work"
|
|
|
|
Make sure you have a [Personal] and a [Work] section, with different
|
|
pathnames. Enable [mbnames].
|
|
|
|
In each account section, do something like this:
|
|
|
|
localfolders = ~/Mail/Personal
|
|
|
|
or
|
|
|
|
localfolders = ~/Mail/Work
|
|
|
|
In Mutt:
|
|
|
|
add lines like this 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
|
|
set spoolfile=+Personal/INBOX
|
|
|
|
That's it!
|
|
|
|
--------------------------------------------------
|
|
|
|
Q. What about the speed of the sync?
|
|
|
|
A. OfflineIMAP 2.0 contains a multithreaded system. A good way to
|
|
experiment is by setting maxsyncaccounts to 3 and maxconnections to 3
|
|
in each account clause.
|
|
|
|
This lets OfflineIMAP open up multiple connections simultaneously.
|
|
That will let it process multiple folders and messages at once. In
|
|
most cases, this will increase performance of the sync.
|
|
|
|
Don't set the number too high. If you do that, things might actually
|
|
slow down as your link gets saturated. Also, too many connections can
|
|
cause mail servers to have excessive load. Administrators might take
|
|
unkindly to this, and the server might bog down. There are many
|
|
variables in the optimal setting; experimentation may help.
|
|
|
|
An informal benchmark yields these results for my setup:
|
|
|
|
OfflineIMAP 2.0 sync with multitreading: 9 seconds
|
|
OfflineIMAP 1.x sync w/o multithreading: 20 seconds
|
|
GNUS sync: 5 minutes
|
|
MacOS X Mail.app "manual cache" method: 10 minutes
|
|
|
|
OfflineIMAP's default configuration example does not have
|
|
multithreading enabled. You must configure it yourself to gain these
|
|
performance benefits. This decision was taken to provide a "works out
|
|
of the box" experience.
|