OfflineIMAP Copyright (C) 2002 John Goerzen 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.