1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
5 >OfflineIMAP Manual
</TITLE
8 CONTENT=
"Modular DocBook HTML Stylesheet Version 1.79"></HEAD
25 >I. OfflineIMAP Manual
</H1
37 > --
Powerful IMAP/Maildir synchronization
38 and reader support
</DT
54 >OfflineIMAP
--
Powerful IMAP/Maildir synchronization
55 and reader support
</DIV
57 CLASS=
"REFSYNOPSISDIV"
115 > is a tool to simplify your e-mail
119 >, you can read the same mailbox
120 from multiple computers. You get a current copy of your
121 messages on each computer, and changes you make one place will be
122 visible on all other systems. For instance, you can delete a message
123 on your home computer, and it will appear deleted on your work
124 computer as well.
<SPAN
127 > is also useful if you want to
128 use a mail reader that does not have IMAP support, has poor IMAP
129 support, or does not provide disconnected operation.
142 my two accounts with over
50 folders in
3 seconds. Other
143 similar tools might take over a minute, and achieve a
144 less-reliable result. Some mail readers can take over
10
145 minutes to do the same thing, and some don't even support it
146 at all. Unlike other mail tools,
<SPAN
150 multi-threaded synchronization algorithm that can dramatically
151 speed up performance in many situations by synchronizing
152 several different things simultaneously.
165 customize which folders are synced via regular expressions,
166 lists, or Python expressions; a versatile and comprehensive
167 configuration file is used to control behavior; two user
168 interfaces are built-in; fine-tuning of synchronization
169 performance is possible; internal or external automation is
170 supported; SSL and PREAUTH tunnels are both supported; offline
171 (or
"unplugged") reading is supported; and esoteric IMAP
172 features are supported to ensure compatibility with the widest
173 variety of IMAP servers.
186 algorithm designed to prevent mail loss at all costs. Because
187 of the design of this algorithm, even programming errors
188 should not result in loss of mail. I am so confident in the
189 algorithm that I use my own personal and work accounts for
193 > pre-release, development, and beta
194 releases. Of course, legally speaking,
<SPAN
198 with no warranty, so I am not responsible if this turns out
207 >Method of Operation
</H3
213 operates by maintaining a hierarchy of
214 mail folders in Maildir format locally. Your own mail
215 reader will read mail from this tree, and need never know
216 that the mail comes from IMAP.
<SPAN
220 changes to the mail folders on your IMAP server and your own
221 computer and bi-directionally synchronize them, copying,
222 marking, and deleting messages as necessary.
228 > 4.0, a powerful new ability has been
229 introduced -- the program can now synchronize two IMAP
230 servers with each other, with no need to have a Maildir
231 layer in-between. Many people use this if they use a mail
232 reader on their local machine that does not support
233 Maildirs. People may install an IMAP server on their local
234 machine, and point both
<SPAN
237 > and their mail reader
238 of choice at it. This is often preferable to the mail
239 reader's own IMAP support since
<SPAN
243 features (offline reading, for one) that most IMAP-aware
244 readers don't. However, this feature is not as time-tested
245 as traditional syncing, so my advice is to stick with normal
246 methods of operation for the time being.
258 >If you have already installed
<SPAN
262 or your system administrator has done that for you, your task
266 > for the first time is quite
267 simple. You just need to set up your configuration file, make
268 your folder directory, and run it!
271 >You can quickly set up your configuration file. The distribution
274 >offlineimap.conf.minimal
</TT
280 >/usr/share/doc/offlineimap/examples/offlineimap.conf.minimal
</TT
281 >) that is a basic example of setting of
<SPAN
285 simply copy this file into your home directory and name it
289 > (note the leading period). A
292 >cp offlineimap.conf.minimal ~/.offlineimaprc
</B
293 > will do it. Or, if you prefer, you can just copy this text to
296 >~/.offlineimaprc
</TT
300 CLASS=
"PROGRAMLISTING"
305 localrepository = Local
306 remoterepository = Remote
310 localfolders = ~/Test
314 remotehost = examplehost
315 remoteuser = jgoerzen
</PRE
319 >~/.offlineimaprc
</TT
321 your favorite editor. All you have to do is specify a directory
322 for your folders to be in (on the
<SPAN
326 line), the host name of your IMAP server (on the
330 > line), and your login name on
331 the remote (on the
<SPAN
340 >, you just have to say
344 > -- it will fire up, ask you for
345 a login password if necessary, synchronize your folders, and exit.
346 See? You can just throw away the rest of this finely-crafted,
347 perfectly-honed manual! Of course, if you want to see how you can
351 > FIVE TIMES FASTER FOR JUST $
19.95 (err, well,
352 $
0), you have to read on!
363 >If you are reading this document via the
"man" command, it is
365 that you have no installation tasks to perform; your system
366 administrator has already installed it. If you need to install it
367 yourself, you have three options: a system-wide installation with
368 Debian, system-wide installation with other systems, and a single-user
369 installation. You can download the latest version of
<SPAN
374 HREF=
"http://quux.org/devel/offlineimap/"
391 >In order to use
<SPAN
394 >, you need to have these conditions
402 >Your mail server must support IMAP. Most Internet Service
404 and corporate networks do, and most operating systems
406 implementation readily available.
411 > You must have Python version
2.2.1 or above installed.
413 running on Debian GNU/Linux, this requirement will automatically be
414 taken care of for you. If you do not have Python already, check with
415 your system administrator or operating system vendor; or, download it from
417 HREF=
"http://www.python.org/"
419 >the Python website
</A
421 If you intend to use the Tk interface, you must have Tkinter
422 (python-tk) installed. If you intend to use the SSL interface, your
423 Python must have been built with SSL support.
428 > Have a mail reader that supports the Maildir mailbox
429 format. Most modern mail readers have this support
430 built-in, so you can choose from a wide variety of mail
431 servers. This format is also known as the
"qmail"
432 format, so any mail reader compatible with it will work
436 >. If you do not have a mail reader
437 that supports Maildir, you can often install a local
438 IMAP server and point both
<SPAN
453 >System-Wide Installation, Debian
</H3
455 > If you are tracking Debian unstable, you may install
459 > by simply running the following command as root:
464 >apt-get install offlineimap
</B
468 > If you are not tracking Debian unstable, download the Debian .deb
470 HREF=
"http://quux.org/devel/offlineimap/"
480 > to install the downloaded
481 package. Then, skip to
<A
482 HREF=
"#CONFIGURATION"
486 > below. You will type
<B
499 >System-Wide Installation, Other
</H3
501 > Download the tar.gz version of the package from the
503 HREF=
"http://quux.org/devel/offlineimap/"
508 these commands, making sure that you are the
"root" user first:
511 CLASS=
"PROGRAMLISTING"
512 >tar -zxvf offlineimap_x.y.z.tar.gz
514 python2.2 setup.py install
</PRE
516 >On some systems, you will need to use
525 HREF=
"#CONFIGURATION"
529 > below. You will type
<B
542 >Single-Account Installation
</H3
544 > Download the tar.gz version of the package from the
546 HREF=
"http://quux.org/devel/offlineimap/"
550 Then run these commands:
553 CLASS=
"PROGRAMLISTING"
554 >tar -zxvf offlineimap_x.y.z.tar.gz
555 cd offlineimap-x.y.z
</PRE
557 >When you want to run
<SPAN
560 >, you will issue the
564 > command as above and then type
568 >; there is no installation
584 > is regulated by a configuration file that is normally
587 >~/.offlineimaprc
</TT
592 ships with a file named
<TT
594 >offlineimap.conf
</TT
596 that you should copy to that location and then edit. This file is
597 vital to proper operation of the system; it sets everything you need
601 >. Full documentation for the configuration file
602 is included within the sample file.
608 > also ships a file named
611 >offlineimap.conf.minimal
</TT
612 > that you can also try.
613 It's useful if you want to get started with
614 the most basic feature set, and you can read about other features
617 >offlineimap.conf
</TT
629 > Most configuration is done via the configuration file. Nevertheless,
630 there are a few command-line options that you may set for
645 >Disable most multithreading operations and use
646 solely a single-connection
647 sync. This effectively sets the
650 >maxsyncaccounts
</SPAN
654 >maxconnections
</SPAN
671 > into profile mode. The program
678 (it must not already exist). As it runs, Python profiling
680 about each thread is logged into profiledir. Please note: This option
681 is present for debugging and optimization only, and should NOT be used
682 unless you have a specific reason to do so. It will significantly
683 slow program performance, may reduce reliability, and can generate
684 huge amounts of data. You must use the
<CODE
710 > section of the configuration
711 file. You might use this to exclude certain accounts, or to sync
712 some accounts that you normally prefer not to. Separate the
713 accounts by commas, and use no embedded spaces.
725 >Specifies a configuration file to use in lieu of
728 >~/.offlineimaprc
</TT
741 >Enables debugging for OfflineIMAP. This is useful if
742 you are trying to track down a malfunction or figure out what is going
743 on under the hood. I suggest that you use this with
747 > to make the results more sensible.
</P
752 > requires one or more debugtypes,
753 separated by commas. These define what exactly will be
754 debugged, and include three options:
<SPAN
769 option will enable IMAP protocol stream and parsing debugging. Note
770 that the output may contain passwords, so take care to remove that
771 from the debugging output before sending it to anyone else. The
775 > option will enable debugging for
776 certain Maildir operations. And
<SPAN
780 will debug the threading model.
793 > Enables logging to filename. This will log everything
794 that goes to the screen to the specified file.
795 Additionally, if any debugging is specified with -d,
796 then debug messages will not go to the screen, but
797 instead to the logfile only.
</P
803 >Run only once, ignoring all
807 > settings in the configuration
814 >Show summary of options.
</P
825 >Specifies an alternative user interface module
826 to use. This overrides the default specified in the
827 configuration file. The pre-defined options are listed in
828 the User Interfaces section.
</P
844 > has a pluggable user interface system that lets you choose how the
845 program communicates information to you. There are two graphical
846 interfaces, two terminal interfaces, and two noninteractive interfaces
847 suitable for scripting or logging purposes. The
851 > option in the configuration file specifies
852 user interface preferences. The
<CODE
856 option can override the configuration file setting. The available
857 values for the configuration file or command-line are described
865 >Tk.Blinkenlights
</H3
867 >Tk.Blinkenlights is an interface designed to be sleek, fun to watch, and
868 informative of the overall picture of what
<SPAN
872 is doing. I consider it to be the best general-purpose interface in
879 > Tk.Blinkenlights contains, by default, a small window with a row of
880 LEDs, a small log, and a row of command buttons.
881 The total size of the window is
882 very small, so it uses little desktop space, yet it is quite
883 functional. The optional, toggleable, log shows more
884 detail about what is happening and is color-coded to match the color
888 > Tk.Blinkenlights is the only user interface that has configurable
889 parameters; see the example
<TT
891 >offlineimap.conf
</TT
896 > Each light in the Blinkenlights interface represents a thread
897 of execution -- that is, a particular task that
<SPAN
901 is performing right now. The colors indicate what task
902 the particular thread is performing, and are as follows:
913 >indicates that this light's thread has terminated; it will light up
914 again later when new threads start up. So, black indicates no
922 >is the color of the main program's thread, which basically does
923 nothing but monitor the others. It might remind you of HAL
9000 in
934 >indicates that the thread is establishing a new connection to the IMAP
942 >is the color of an account synchronization thread that is monitoring
943 the progress of the folders in that account (not generating any I/O).
950 >indicates that the thread is syncing a folder.
957 >means that a folder's message list is being loaded.
964 >is the color of a message synchronization controller thread.
971 >indicates that an actual message is being copied.
972 (We use fuchsia for fake messages.)
979 >indicates that a message is being deleted.
983 >Yellow / bright orange
</DT
986 >indicates that message flags are being added.
990 >Pink / bright red
</DT
993 >indicates that message flags are being removed.
997 >Red / Black Flashing
</DT
1000 >corresponds to the countdown timer that runs between
1007 >The name of this interfaces derives from a bit of computer
1008 history. Eric Raymond's [
<SPAN
1023 >Front-panel diagnostic
1024 lights on a computer, esp. a dinosaur. Now that dinosaurs are rare,
1025 this term usually refers to status lights on a modem, network hub, or
1029 > This term derives from the last word of the famous blackletter-Gothic
1030 sign in mangled pseudo-German that once graced about half the computer
1031 rooms in the English-speaking world. One version ran in its entirety as
1039 >ACHTUNG! ALLES LOOKENSPEEPERS!
</I
1044 > Das computermachine ist nicht fuer gefingerpoken und mittengrabben.
1045 Ist easy schnappen der springenwerk, blowenfusen und poppencorken
1046 mit spitzensparken. Ist nicht fuer gewerken bei das dumpkopfen.
1047 Das rubbernecken sichtseeren keepen das cotten-pickenen hans in das
1048 pockets muss; relaxen und watchen das blinkenlichten.
1058 >Curses.Blinkenlights
</H3
1060 > Curses.Blinkenlights is an interface very similar to Tk.Blinkenlights,
1061 but is designed to be run in a console window (an xterm, Linux virtual
1062 terminal, etc.) Since it doesn't have access to graphics, it isn't
1063 quite as pretty, but it still gets the job done.
1066 >Please see the Tk.Blinkenlights section above for more
1067 information about the colors used in this interface.
1078 > Tk.VerboseUI (formerly known as Tk.TkUI) is a graphical interface
1079 that presents a variable-sized window. In the window, each
1080 currently-executing thread has a section where its name and current
1081 status are displayed. This interface is best suited to people running
1082 on slower connections, as you get a lot of detail, but for fast
1083 connections, the detail may go by too quickly to be useful. People
1084 with fast connections may wish to use Tk.Blinkenlights instead.
1095 > TTY.TTYUI interface is for people running in basic, non-color terminals. It
1096 prints out basic status messages and is generally friendly to use on a console
1106 >Noninteractive.Basic
</H3
1108 > Noninteractive.Basic is designed for situations in which
<SPAN
1112 will be run non-attended and the status of its execution will be
1113 logged. You might use it, for instance, to have the system run
1115 e-mail you the results of the synchronization. This user interface
1116 is not capable of reading a password from the keyboard; account
1117 passwords must be specified using one of the configuration file options.
1126 >Noninteractive.Quiet
</H3
1128 > Noninteractive.Quiet is designed for non-attended running in situations
1129 where normal status messages are not desired. It will output nothing
1130 except errors and serious warnings. Like Noninteractive.Basic,
1132 is not capable of reading a password from the keyboard; account
1133 passwords must be specified using one of the configuration file options.
1145 >Here are some example configurations for various situations.
1146 Please e-mail any other examples you have that may be useful to
1155 >Multiple Accounts with Mutt
</H3
1157 > This example shows you how to set up
<SPAN
1161 synchronize multiple accounts with the mutt mail reader.
1164 > Start by creating a directory to hold your folders by running
1171 >~/.offlineimaprc
</TT
1175 CLASS=
"PROGRAMLISTING"
1176 >accounts = Personal, Work
</PRE
1178 > Make sure that you have both an
1181 >[Account Personal]
</SPAN
1185 >[Account Work]
</SPAN
1187 local repository for each account must have different
1199 > In each local repository section, write something like this:
1202 CLASS=
"PROGRAMLISTING"
1203 >localfolders = ~/Mail/Personal
</PRE
1205 > Finally, add these lines to your
<TT
1211 CLASS=
"PROGRAMLISTING"
1212 >source ~/path-to-mbnames-muttrc-mailboxes
1213 folder-hook Personal set
from=
"youremail@personal.com"
1214 folder-hook Work set
from=
"youremail@work.com"
1215 set mbox_type=Maildir
1216 set folder=$HOME/Mail
1217 spoolfile=+Personal/INBOX
</PRE
1228 >UW-IMAPD and References
</H3
1230 >Some users with a UW-IMAPD server need to use
<SPAN
1234 "reference" feature to get at their mailboxes, specifying a reference
1235 of
"~/Mail" or
"#mh/" depending on the configuration. The below
1236 configuration from (originally from docwhat@gerf.org)
1245 the leading Mail/ off incoming folder names, and a
1250 limits the folders synced to just three.
1253 CLASS=
"PROGRAMLISTING"
1255 localrepository = GerfLocal
1256 remoterepository = GerfRemote
1258 [Repository GerfLocal]
1260 localfolders = ~/Mail
1262 [Repository GerfRemote]
1264 remotehost = gerf.org
1266 remoteuser = docwhat
1268 # Trims off the preceeding Mail on all the folder names.
1269 nametrans = lambda foldername: \
1270 re.sub('^Mail/', '', foldername)
1271 # Yeah, you have to mention the Mail dir, even though it
1272 # would seem intuitive that reference would trim it.
1273 folderfilter = lambda foldername: foldername in [
1275 'Mail/list/zaurus-general',
1276 'Mail/list/zaurus-dev',
1279 holdconnectionopen = no
</PRE
1287 >pythonfile Configuration File Option
</H3
1293 load up a Python file before evaluating the
1294 configuration file options that are Python expressions. This example
1295 is based on one supplied by Tommi Virtanen for this feature.
1300 >~/.offlineimap.rc
</TT
1301 >, he adds these options:
1304 CLASS=
"PROGRAMLISTING"
1306 pythonfile=~/.offlineimap.py
1308 foldersort=mycmp
</PRE
1312 >~/.offlineimap.py
</TT
1317 CLASS=
"PROGRAMLISTING"
1318 >prioritized = ['INBOX', 'personal', 'announce', 'list']
1321 for prefix in prioritized:
1322 xsw = x.startswith(prefix)
1323 ysw = y.startswith(prefix)
1334 folders=os.listdir(os.path.expanduser('~/data/mail/tv@hq.yok.utu.fi'))
1338 > This code snippet illustrates how the
<SPAN
1342 option can be customized with a Python function from the
1346 > to always synchronize certain
1359 > If you get one of some frequently-encountered or confusing errors,
1360 please check this section.
1368 >UID validity problem for folder
</H3
1370 >IMAP servers use a unique ID (UID) to refer to a specific message.
1371 This number is guaranteed to be unique to a particular message
1379 No other message in the same folder will ever get the same
1380 UID. UIDs are an integral part of
<SPAN
1384 scheme; they are used to match up messages on your computer to
1385 messages on the server.
1388 > Sometimes, the UIDs on the server might get reset. Usually this will
1389 happen if you delete and then recreate a folder. When you create a
1390 folder, the server will often start the UID back from
1. But
1394 > might still have the UIDs from the previous folder by the
1395 same name stored.
<SPAN
1398 > will detect this condition and skip the
1399 folder. This is GOOD, because it prevents data loss.
1402 > You can fix it by removing your local folder and cache data. For
1403 instance, if your folders are under
<TT
1407 and the folder with the problem is INBOX, you'd type this:
1410 CLASS=
"PROGRAMLISTING"
1411 >rm -r ~/Folders/INBOX
1412 rm -r ~/.offlineimap/Account-
<TT
1418 rm -r ~/.offlineimap/Repository-
<TT
1425 > (Of course, replace AccountName and RepositoryName
1426 with the names as specified
1429 >~/.offlineimaprc
</TT
1433 >Next time you run
<SPAN
1436 >, it will re-download
1438 new UIDs. Note that the procedure specified above will lose any local
1439 changes made to the folder.
1442 > Some IMAP servers are broken and do not support UIDs properly. If you
1443 continue to get this error for all your folders even after performing
1444 the above procedure, it is likely that your IMAP server falls into
1445 this category.
<SPAN
1448 > is incompatible with such servers.
1452 > with them will not destroy any mail, but at the same time,
1453 it will not actually synchronize it either. (
<SPAN
1457 this condition and abort prior to synchronization.)
1460 > This question comes up frequently on the
1462 HREF=
"http://lists.complete.org/offlineimap@complete.org/"
1471 HREF=
"http://lists.complete.org/offlineimap@complete.org/2003/04/msg00012.html.gz"
1475 > of the problem there.
1484 >Use with MS Exchange server
</H3
1486 > Several users have reported problems with Microsoft Exchange
1487 servers in conjunction with OfflineIMAP. This generally
1488 seems to be related to the Exchange servers not properly
1489 following the IMAP standards.
1492 > Mark Biggers has posted some
<A
1493 HREF=
"http://lists.complete.org/offlineimap@complete.org/2005/09/msg00011.html.gz"
1500 > mailing list about how he made it work.
1503 > Other users have indicated that older (
5.5) releases of
1504 Exchange are so bad that they will likely not work at all.
1507 > I do not have access to Exchange servers for testing, so any
1508 problems with it, if they can even be solved at all, will
1509 require help from
<SPAN
1512 > users to find and fix.
1522 >Other Frequently Asked Questions
</H2
1524 >There are some other FAQs that might not fit into another section
1525 of the document, so they are discussed here.
1530 CLASS=
"VARIABLELIST"
1533 >What platforms does
<SPAN
1539 > It should run on most platforms supported by Python, which are quite a
1540 few. I do not support Windows myself, but some have made
1541 it work there; see the FAQ entry for that platform.
1545 >I'm using Mutt. Other IMAP sync programs require me to use
"set maildir_trash=yes". Do I need to do that with
<SPAN
1554 > is smart enough to figure out message deletion without this extra
1555 crutch. You'll get the best results if you don't use this setting, in
1560 >I've upgraded and now
<SPAN
1564 crashes when I start it up! Why?
</DT
1567 >You need to upgrade your configuration
1568 file. See at the end of this
1573 >How do I specify the names of my folders?
</DT
1576 > You do not need to.
<SPAN
1580 enough to automatically figure out what folders are present
1581 on the IMAP server and synchronize them. You can use the
1589 configuration file options to request certain folders and rename them
1590 as they come in if you like.
1594 >How can I prevent certain folders from being synced?
</DT
1600 > option in the configuration file.
1604 >How can I add or delete a folder?
</DT
1610 > does not currently provide this feature, but if you create a new
1611 folder on the IMAP server, it will be created locally automatically.
1615 >Are there any other warnings that I should be aware of?
</DT
1618 > Yes; see the Notes section below.
1622 >What is the mailbox name recorder (mbnames) for?
</DT
1625 >Some mail readers, such as Mutt, are not capable
1626 of automatically determining the names of your mailboxes.
1630 > can help these programs by writing the names
1631 of the folders in a format you specify. See the example
1634 >offlineimap.conf
</TT
1639 >Can I synchronize multiple accounts with
<SPAN
1645 >Sure. Just name them all in the
1653 section of the configuration file, and add a per-account section
1664 >No. POP is not robust enough to do a completely reliable
1665 multi-machine synchronization like
<SPAN
1672 will not support it.
1679 > support mailbox formats other than Maildir?
</DT
1682 >Not at present. There is no technical reason not to; just no
1683 demand yet. Maildir is a superior format anyway.
1687 > can sync between two IMAP
1688 servers, and some IMAP servers support other formats. You
1689 could install an IMAP server on your local machine and have
1697 >[technical] Why are your Maildir message filenames so huge?
</DT
1703 > has two relevant principles:
1) never modifying your
1704 messages in any way and
2) ensuring
100% reliable synchronizations.
1705 In order to do a reliable sync,
<SPAN
1710 uniquely identify each e-mail. Three pieces of information are
1711 required to do this: your account name, the folder name, and the
1712 message UID. The account name can be calculated from the path in
1713 which your messages are. The folder name can usually be as well, BUT
1714 some mail clients move messages between folders by simply moving the
1715 file, leaving the name intact.
1721 > must store both a UID folder ID. The folder ID is
1725 > can detect a message moved to a different
1729 > stores the UID (U= number) and an md5sum of the
1730 foldername (FMD5= number) to facilitate this.
1734 >What is the speed of
<SPAN
1741 versions
2.0 and above contain a multithreaded system. A good way to
1742 experiment is by setting
<SPAN
1744 >maxsyncaccounts
</SPAN
1747 >maxconnections
</SPAN
1749 in each account clause.
1752 >This lets OfflineIMAP open up multiple connections simultaneously.
1753 That will let it process multiple folders and messages at once. In
1754 most cases, this will increase performance of the sync.
1757 >Don't set the number too high. If you do that, things might actually
1758 slow down as your link gets saturated. Also, too many connections can
1759 cause mail servers to have excessive load. Administrators might take
1760 unkindly to this, and the server might bog down. There are many
1761 variables in the optimal setting; experimentation may help.
1764 >An informal benchmark yields these results for my setup:
1771 >10 minutes with MacOS X Mail.app
"manual cache"
1776 >5 minutes with GNUS agent sync
</P
1780 >20 seconds with OfflineIMAP
1.x
</P
1784 >9 seconds with OfflineIMAP
2.x
</P
1788 >3 seconds with OfflineIMAP
3.x
"cold start"</P
1792 >2 seconds with OfflineIMAP
3.x
"held connection"</P
1803 > These answers have been reported by
<SPAN
1807 users. I do not run
<SPAN
1810 > on Windows myself, so
1811 I can't directly address their accuracy.
1814 > The basic answer is that it's possible and doesn't
1815 require hacking
<SPAN
1818 > source code. However,
1819 it's not necessarily trivial. The information below is
1820 based in instructions submitted by Chris Walker.
1823 > First, you must run
<SPAN
1827 HREF=
"http://www.cygwin.com/"
1834 > Next, you'll need to mount your Maildir directory in a
1835 special way. There is information for doing that at
1837 HREF=
"http://barnson.org/node/view/295"
1839 >http://barnson.org/node/view/
295</A
1841 That site gives this example:
1844 CLASS=
"PROGRAMLISTING"
1845 >mount -f -s -b -o managed
"d:/tmp/mail" "/home/of/mail"
1848 > That URL also has more details on making OfflineIMAP
1867 >Internet Message Access Protocol version
4rev1 (IMAP
4rev1) as
1868 specified in RFC2060 and RFC3501
</P
1872 >CRAM-MD5 as specified in RFC2195
</P
1876 >Maildir as specified in
1878 HREF=
"http://www.qmail.org/qmail-manual-html/man5/maildir.html"
1880 >the Maildir manpage
</A
1883 HREF=
"http://cr.yp.to/proto/maildir.html"
1885 >the qmail website
</A
1890 >Standard Python
2.2.1 as implemented on POSIX-compliant systems.
</P
1907 >Deleting Local Folders
</H3
1912 > does a two-way synchronization. That is, if you
1913 make a change to the mail on the server, it will be propagated to your
1914 local copy, and vise-versa. Some people might think that it would be
1915 wise to just delete all their local mail folders periodically. If you
1919 >, remember to also remove your local status
1923 > by default). Otherwise,
<SPAN
1927 this as an intentional deletion of many messages and will interpret
1928 your action as requesting them to be deleted from the server as well.
1929 (If you don't understand this, don't worry; you probably won't
1930 encounter this situation)
1939 >Multiple Instances
</H3
1944 > is not designed to have several instances (for instance, a cron job and an interactive invocation) run over the same
1945 mailbox simultaneously. It will perform a check on startup and
1946 abort if another
<SPAN
1949 > is already running. If you need
1950 to schedule synchronizations, please use the
1954 > settings rather than cron.
1955 Alternatively, you can set a separate
<SPAN
1959 directory for each instance.
1968 >Copying Messages Between Folders
</H3
1970 > Normally, when you copy a message between folders or add a new message
1971 to a folder locally,
<SPAN
1975 will just do the right thing. However, sometimes this can be tricky
1976 -- if your IMAP server does not provide the SEARCH command, or does
1977 not return something useful,
<SPAN
1981 cannot determine the new UID of the message. So, in these rare
1982 instances, OfflineIMAP will upload the message to the IMAP server and
1983 delete it from your local folder. Then, on your next sync, the
1984 message will be re-downloaded with the proper UID.
1988 > makes sure that the message was properly uploaded before deleting it,
1989 so there should be no risk of data loss.
1998 >Use with Evolution
</H3
2003 > can work with Evolution. To do so, first configure
2011 > in its configuration. Then, configure
2013 "Maildir-format mail directories" server type. For the path, you will need to
2014 specify the name of the top-level folder
2036 >At this time, I believe that
<SPAN
2041 with KMail. KMail cannot work in any mode other than to move
2042 all messages out of all folders immediately, which (besides being annoying
2043 and fundamentally broken) is incompatible with
2050 > However, I have made KMail version
3 work well with
2054 > by installing an IMAP server on my local
2055 machine, having
<SPAN
2058 > sync to that, and pointing
2059 KMail at the same server.
2070 >There is an OfflineIMAP mailing list available.
2071 To subscribe, send the text
"Subscribe" in the subject of a mail to
2072 offlineimap-request@complete.org. To post, send the message to
2073 offlineimap@complete.org. Archives are available at
2075 HREF=
"http://lists.complete.org/offlineimap@complete.org/"
2077 >http://lists.complete.org/offlineimap@complete.org/
</A
2089 >Reports of bugs should be sent via e-mail to the
2093 > mailing list at offlineimap at complete
2094 dot org. Debian users are encouraged to instead use the
2096 bug-tracking system.
2103 NAME=
"UPGRADING.4.0"
2106 >Upgrading to
4.0</H2
2108 > If you are upgrading from a version of
<SPAN
2112 3.99.12, you will find that you will get errors when
2116 > starts up (relating to ConfigParser or
2117 AccountHashGenerator) and the
2118 configuration file. This is because the config file format
2119 had to change to accommodate new features in
4.0. Fortunately,
2120 it's not difficult to adjust it to suit.
2123 > First thing you need to do is stop any running
<SPAN
2127 instance, making sure first that it's synced all your mail.
2131 >~/.offlineimaprc
</TT
2132 > file. You'll need to
2133 split up each account section (make sure that it now starts
2134 with
"Account ") into two Repository sections (one for the
2135 local side and another for the remote side.) See the files
2138 >offlineimap.conf.minimal
</TT
2142 >offlineimap.conf
</TT
2143 > in the distribution if
2144 you need more assistance.
2150 >'s status directory area has also changed.
2151 Therefore, you should delete everything in ~/.offlineimap as
2152 well as your local mail folders.
2155 > When you start up
<SPAN
2158 > 4.0, it will re-download all
2159 your mail from the server and then you can continue using it
2171 >OfflineIMAP, and this manual, are Copyright
© 2002,
2003 John Goerzen.
</P
2173 > This program is free software; you can redistribute it and/or modify
2174 it under the terms of the GNU General Public License as published by
2175 the Free Software Foundation; either version
2 of the License, or
2176 (at your option) any later version.
2179 > This program is distributed in the hope that it will be useful,
2180 but WITHOUT ANY WARRANTY; without even the implied warranty of
2181 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
2182 GNU General Public License for more details.
2185 > You should have received a copy of the GNU General Public License
2186 along with this program; if not, write to the Free Software
2187 Foundation, Inc.,
59 Temple Place, Suite
330, Boston, MA
02111-
1307 USA
</P
2189 >imaplib.py comes from the Python dev tree and is licensed under
2190 the GPL-compatible PSF license as stated in the file
2212 >, its libraries, documentation, and all included files, except where
2213 noted, was written by John Goerzen
<CODE
2216 HREF=
"mailto:jgoerzen@complete.org"
2217 >jgoerzen@complete.org
</A
2220 copyright is held as stated in the COPYRIGHT section.
2226 > may be downloaded, and information found, from its
2227 homepage via either
<A
2228 HREF=
"gopher://quux.org/1/devel/offlineimap"
2233 HREF=
"http://quux.org/devel/offlineimap"
2242 > may also be downloaded using Subversion. Additionally,
2243 the distributed tar.gz may be updated with a simple
"svn update"
2244 command; it is ready to go. For information on getting OfflineIMAP
2245 with Subversion, please visit the
2247 HREF=
"http://svn.complete.org/"
2249 >complete.org Subversion page
</A
2279 > Detailed history may be found in the file ChangeLog in the
2283 > distribution. Feature and bug histories may be
2284 found in the file debian/changelog which, despite its name, is
2285 not really Debian-specific. This section provides a large
2289 > Development on
<SPAN
2292 > began on June
18,
2002. Version
2293 1.0.0 was released three days later on June
21,
2002. Point
2294 releases followed, including speed optimizations and some
2295 compatibility fixes.
2298 >Version
2.0.0 was released on July
3,
2002, and
2299 represented the first time the synchronization became
2300 multithreaded and, to the best of my knowledge, the first
2301 multithreaded IMAP syncrhonizing application in existance.
2302 The last
2.0.x release,
2.0.8, was made on July
9.
2305 > Version
3.0.0 was released on July
11,
2002, and introduced
2306 modular user interfaces and the first GUI interface for
2310 >. This manual also was introduced with
3.0.0,
2311 along with many command-line options. Version
3.1.0 was
2312 released on July
21, adding the Noninteractive user
2313 interfaces, profiling support, and several bugfixes.
3.2.0
2314 was released on July
24, adding support for the Blinkenlights
2315 GUI interface.
<SPAN
2318 > entered maintenance mode for
2319 awhile, as it had reached a feature-complete milestone in my
2323 > The
3.99.x branch began in on October
7,
2002, to begin work
2324 for
4.0. The Curses.Blinkenlights interface was added in
2325 3.99.6, and many architectural changes were made.
2328 > 4.0.0 was released on July
18,
2003, including the ability to
2329 synchronize directly between two IMAP servers, the first
2330 re-architecting of the configuration file to refine the
2331 notion of an account, and the new Curses interface.