docker-offlineimap/manual.txt

OFFLINEIMAP(1)                OfflineIMAP Manual                OFFLINEIMAP(1)



NAME
       OfflineIMAP - Powerful IMAP/Maildir synchronization and reader support

SYNOPSIS
       offlineimap [ -1 ] [ -P profiledir ] [ -a accountlist ] [ -c configfile
       ] [ -d debugtype[,...] ] [ -l filename ] [ -o ] [ -u interface ]


       offlineimap -h | --help


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.

       OfflineIMAP is FAST; it synchronizes my two accounts with over 50 fold-
       ers in 3 seconds.  Other similar tools might take over  a  minute,  and
       achieve  a  less-reliable  result.   Some mail readers can take over 10
       minutes to do the same thing, and some don't even support  it  at  all.
       Unlike other mail tools, OfflineIMAP features a multi-threaded synchro-
       nization algorithm that can dramatically speed up performance  in  many
       situations by synchronizing several different things simultaneously.

       OfflineIMAP is FLEXIBLE; you can customize which folders are synced via
       regular expressions, lists, or Python expressions; a versatile and com-
       prehensive  configuration  file  is  used to control behavior; two user
       interfaces are built-in; fine-tuning of synchronization performance  is
       possible; internal or external automation is supported; SSL and PREAUTH
       tunnels are both supported; offline (or "unplugged")  reading  is  sup-
       ported;  and esoteric IMAP features are supported to ensure compatibil-
       ity with the widest variety of IMAP servers.

       OfflineIMAP is SAFE; it uses an algorithm designed to prevent mail loss
       at  all  costs.  Because of the design of this algorithm, even program-
       ming errors should not result in loss of mail.  I am  so  confident  in
       the  algorithm that I use my own personal and work accounts for testing
       of OfflineIMAP pre-release, development, and beta releases.  Of course,
       legally  speaking,  OfflineIMAP  comes  with  no  warranty, so I am not
       responsible if this turns out to be wrong.

   METHOD OF OPERATION
       OfflineIMAP traditionally operates by maintaining a hierarchy  of  mail
       folders in Maildir format locally.  Your own mail reader will read mail
       from this tree, and need never know that  the  mail  comes  from  IMAP.
       OfflineIMAP will detect changes to the mail folders on your IMAP server
       and your own computer and bi-directionally synchronize  them,  copying,
       marking, and deleting messages as necessary.

       With OfflineIMAP 4.0, a powerful new ability has been introduced -- the
       program can now synchronize two IMAP servers with each other,  with  no
       need  to have a Maildir layer in-between.  Many people use this if they
       use a mail  reader  on  their  local  machine  that  does  not  support
       Maildirs.   People  may  install an IMAP server on their local machine,
       and point both OfflineIMAP and their mail reader of choice at it.  This
       is  often  preferable  to  the  mail  reader's  own  IMAP support since
       OfflineIMAP supports many features (offline reading, for one) that most
       IMAP-aware  readers don't.  However, this feature is not as time-tested
       as traditional syncing, so my advice is to stick with normal methods of
       operation for the time being.

QUICK START
       If  you  have already installed OfflineIMAP system-wide, or your system
       administrator  has  done  that  for  you,  your  task  for  setting  up
       OfflineIMAP  for  the first time is quite simple.  You just need to set
       up your configuration file, make your folder directory, and run it!

       You can quickly set  up  your  configuration  file.   The  distribution
       includes a file offlineimap.conf.minimal (Debian users may find this at
       /usr/share/doc/offlineimap/examples/offlineimap.conf.minimal) that is a
       basic example of setting of OfflineIMAP.  You can simply copy this file
       into your home directory and name it .offlineimaprc (note  the  leading
       period).     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 remote-
       host line), and your login name on the remote (on the remoteuser line).
       That's it!

       To  run  OfflineIMAP,  you just have to say offlineimap -- it will fire
       up, ask you for a login password if necessary, synchronize  your  fold-
       ers,  and exit.  See?  You can just throw away the rest of this finely-
       crafted, perfectly-honed 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!

INSTALLATION
       If you are reading this document via the "man" command,  it  is  likely
       that you have no installation tasks to perform; your system administra-
       tor has already installed it.  If you need to install it yourself,  you
       have three options: a system-wide installation with Debian, system-wide
       installation with other systems, and a single-user  installation.   You
       can  download  the  latest  version of OfflineIMAP from the OfflineIMAP
       website <URL:http://software.complete.org/offlineimap/>.

   PREREQUISITES
       In order to use OfflineIMAP, you need to have these  conditions  satis-
       fied:

       o Your  mail server must support IMAP.  Most Internet Service Providers
         and corporate networks do, and most operating systems  have  an  IMAP
         implementation readily available.

       o You  must  have  Python version 2.2.1 or above installed.  If you are
         running on Debian GNU/Linux, this requirement will  automatically  be
         taken care of for you.  If you do not have Python already, check with
         your system administrator or operating system vendor; or, download it
         from  the Python website <URL:http://www.python.org/>.  If you intend
         to use the Tk interface, you must have Tkinter (python-tk) installed.
         If  you  intend  to use the SSL interface, your Python must have been
         built with SSL support.

       o Have a mail reader that supports the Maildir  mailbox  format.   Most
         modern  mail  readers  have  this support built-in, so you can choose
         from a wide variety of mail servers.  This format is  also  known  as
         the  "qmail"  format, so any mail reader compatible with it will work
         with OfflineIMAP.  If you do not have a  mail  reader  that  supports
         Maildir,  you  can  often  install a local IMAP server and point both
         OfflineIMAP and your mail reader at it.

   SYSTEM-WIDE INSTALLATION, DEBIAN
       If you are tracking Debian unstable, you  may  install  OfflineIMAP  by
       simply running the following command as root:

       apt-get install offlineimap

       If you are not tracking Debian unstable, download the Debian .deb pack-
       age   from   the    OfflineIMAP    website    <URL:http://software.com-
       plete.org/offlineimap/>  and then run dpkg -i to install the downloaded
       package.  Then, skip to [XRef to CONFIGURATION] below.  You  will  type
       offlineimap to invoke the program.

   SYSTEM-WIDE INSTALLATION, OTHER
       Download   the   tar.gz   version  of  the  package  from  the  website
       <URL:http://software.complete.org/offlineimap/>.  Then run  these  com-
       mands, making sure that you are the "root" user first:

       tar -zxvf offlineimap_x.y.z.tar.gz
       cd offlineimap-x.y.z
       python2.2 setup.py install

       On  some  systems,  you  will  need to use python instead of python2.2.
       Next,  proceed  to  [XRef  to  CONFIGURATION]  below.   You  will  type
       offlineimap to invoke the program.

   SINGLE-ACCOUNT INSTALLATION
       Download   the   tar.gz   version  of  the  package  from  the  website
       <URL:http://software.complete.org/offlineimap/>.  Then run  these  com-
       mands:

       tar -zxvf offlineimap_x.y.z.tar.gz
       cd offlineimap-x.y.z

       When  you  want  to  run  OfflineIMAP, you will issue the cd command as
       above and then type ./offlineimap.py; there  is  no  installation  step
       necessary.

CONFIGURATION
       OfflineIMAP  is  regulated  by  a  configuration  file that is normally
       stored in  ~/.offlineimaprc.   OfflineIMAP  ships  with  a  file  named
       offlineimap.conf  that  you should copy to that location and then edit.
       This file is vital to proper operation of the system;  it  sets  every-
       thing you need to run OfflineIMAP.  Full documentation for the configu-
       ration file is included within the sample file.

       OfflineIMAP also ships a file named offlineimap.conf.minimal  that  you
       can  also  try.   It's  useful if you want to get started with the most
       basic feature set, and you can read about  other  features  later  with
       offlineimap.conf.

OPTIONS
       Most  configuration  is done via the configuration file.  Nevertheless,
       there are a few command-line options that you may set for  OfflineIMAP.

       -1     Disable  most multithreading operations and use solely a single-
              connection sync.  This effectively sets the maxsyncaccounts  and
              all maxconnections configuration file variables to 1.

       -P profiledir
              Sets  OfflineIMAP  into  profile  mode.  The program will create
              profiledir (it must not already exist).  As it runs, Python pro-
              filing  information about each thread is logged into profiledir.
              Please note: This option is present for debugging and  optimiza-
              tion  only,  and  should  NOT be used unless you have a specific
              reason to do so.  It will  significantly  slow  program  perfor-
              mance,  may reduce reliability, and can generate huge amounts of
              data.  You must use the -1 option when you use -P.

       -a accountlist
              Overrides the accounts option in the general section of the con-
              figuration   file.   You  might  use  this  to  exclude  certain
              accounts, or to sync some accounts that you normally prefer  not
              to.   Separate  the  accounts  by  commas,  and  use no embedded
              spaces.

       -c configfile
              Specifies a configuration file to use in lieu  of  the  default,
              ~/.offlineimaprc.

       -d debugtype[,...]
              Enables  debugging  for  OfflineIMAP.  This is useful if you are
              trying to track down a malfunction or figure out what  is  going
              on  under the hood.  I suggest that you use this with -1 to make
              the results more sensible.

              -d requires one or more debugtypes, separated by commas.   These
              define what exactly will be debugged, and include three options:
              imap, maildir, and thread.  The imap  option  will  enable  IMAP
              protocol stream and parsing debugging.  Note that the output may
              contain passwords, so take care to remove that from  the  debug-
              ging  output  before  sending  it  to  anyone else.  The maildir
              option will enable debugging  for  certain  Maildir  operations.
              And thread will debug the threading model.

       -l filename
              Enables logging to filename.  This will log everything that goes
              to the screen to  the  specified  file.   Additionally,  if  any
              debugging  is specified with -d, then debug messages will not go
              to the screen, but instead to the logfile only.

       -o     Run only once, ignoring all autorefresh settings in the configu-
              ration file.

       -h

       --help Show summary of options.

       -u interface
              Specifies  an  alternative  user  interface module to use.  This
              overrides the default specified in the configuration file.   The
              pre-defined options are listed in the User Interfaces section.

USER INTERFACES
       OfflineIMAP  has a pluggable user interface system that lets you choose
       how the program communicates information to you.  There are two graphi-
       cal  interfaces, two terminal interfaces, and two noninteractive inter-
       faces suitable for scripting or logging purposes.  The ui option in the
       configuration  file  specifies user interface preferences.  The -u com-
       mand-line option can override  the  configuration  file  setting.   The
       available  values  for  the  configuration  file  or  command-line  are
       described in this section.

   TK.BLINKENLIGHTS
       Tk.Blinkenlights is an interface designed to be sleek,  fun  to  watch,
       and informative of the overall picture of what OfflineIMAP is doing.  I
       consider it to be the best general-purpose interface in OfflineIMAP.

       Tk.Blinkenlights contains, by default, a small window  with  a  row  of
       LEDs, a small log, and a row of command buttons.  The total size of the
       window is very small, so it uses little desktop space, yet it is  quite
       functional.  The optional, toggleable, log shows more detail about what
       is happening and is color-coded to match the color of the lights.

       Tk.Blinkenlights is the  only  user  interface  that  has  configurable
       parameters; see the example offlineimap.conf for more details.

       Each light in the Blinkenlights interface represents a thread of execu-
       tion -- that is, a particular task that OfflineIMAP is performing right
       now.   The  colors indicate what task the particular thread is perform-
       ing, and are as follows:

       Black  indicates that this light's thread has terminated; it will light
              up  again  later when new threads start up.  So, black indicates
              no activity.

       Red (Meaning 1)
              is the color of the main program's thread, which basically  does
              nothing but monitor the others.  It might remind you of HAL 9000
              in 2001.

       Gray   indicates that the thread is establishing a  new  connection  to
              the IMAP server.

       Purple is  the color of an account synchronization thread that is moni-
              toring the progress of the folders in that account (not generat-
              ing any I/O).

       Cyan   indicates that the thread is syncing a folder.

       Green  means that a folder's message list is being loaded.

       Blue   is the color of a message synchronization controller thread.

       Orange indicates that an actual message is being copied.  (We use fuch-
              sia for fake messages.)

       Red (meaning 2)
              indicates that a message is being deleted.

       Yellow / bright orange
              indicates that message flags are being added.

       Pink / bright red
              indicates that message flags are being removed.

       Red / Black Flashing
              corresponds to the countdown timer that  runs  between  synchro-
              nizations.

       The  name  of  this  interfaces derives from a bit of computer history.
       Eric Raymond's Jargon File defines blinkenlights, in part, as:


              Front-panel diagnostic lights on a computer,  esp.  a  dinosaur.
              Now  that dinosaurs are rare, this term usually refers to status
              lights on a modem, network hub, or the like.

              This term derives from the last word of the famous  blackletter-
              Gothic sign in mangled pseudo-German that once graced about half
              the computer rooms in the English-speaking  world.  One  version
              ran in its entirety as follows:

              ACHTUNG!  ALLES LOOKENSPEEPERS!

              Das  computermachine  ist  nicht  fuer gefingerpoken und mitten-
              grabben.  Ist easy schnappen der springenwerk,  blowenfusen  und
              poppencorken  mit  spitzensparken.   Ist nicht fuer gewerken bei
              das dumpkopfen.  Das rubbernecken sichtseeren keepen das cotten-
              pickenen  hans  in  das  pockets  muss;  relaxen und watchen das
              blinkenlichten.

   CURSES.BLINKENLIGHTS
       Curses.Blinkenlights is an interface very similar to  Tk.Blinkenlights,
       but  is designed to be run in a console window (an xterm, Linux virtual
       terminal, etc.)  Since it doesn't have access  to  graphics,  it  isn't
       quite as pretty, but it still gets the job done.

       Please  see  the  Tk.Blinkenlights  section  above for more information
       about the colors used in this interface.

   TK.VERBOSEUI
       Tk.VerboseUI (formerly known as Tk.TkUI) is a graphical interface  that
       presents  a  variable-sized window.  In the window, each currently-exe-
       cuting thread has a section where its name and current status are  dis-
       played.  This interface is best suited to people running on slower con-
       nections, as you get a lot of detail, but  for  fast  connections,  the
       detail  may  go  by too quickly to be useful.  People with fast connec-
       tions may wish to use Tk.Blinkenlights instead.

   TTY.TTYUI
       TTY.TTYUI interface is for people running in  basic,  non-color  termi-
       nals.  It prints out basic status messages and is generally friendly to
       use on a console or xterm.

   NONINTERACTIVE.BASIC
       Noninteractive.Basic is designed for situations  in  which  OfflineIMAP
       will  be  run  non-attended  and  the  status  of its execution will be
       logged.  You might use it, for instance, to have the system  run  auto-
       matically and e-mail you the results of the synchronization.  This user
       interface is not capable of  reading  a  password  from  the  keyboard;
       account passwords must be specified using one of the configuration file
       options.

   NONINTERACTIVE.QUIET
       Noninteractive.Quiet is designed for non-attended running in situations
       where  normal  status messages are not desired.  It will output nothing
       except errors and serious warnings.   Like  Noninteractive.Basic,  this
       user  interface is not capable of reading a password from the keyboard;
       account passwords must be specified using one of the configuration file
       options.

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  multi-
       ple 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 differ-
       ent 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 ~/.offlineimap.rc, 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 cus-
       tomized with a Python function from the pythonfile to  always  synchro-
       nize certain folders first.

ERRORS
       If  you  get  one  of  some frequently-encountered or confusing errors,
       please check this section.

   UID VALIDITY PROBLEM FOR FOLDER
       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 -r ~/.offlineimap/Account-AccountName
       rm -r ~/.offlineimap/Repository-RepositoryName

       (Of  course,  replace  AccountName and RepositoryName with the names 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.)

       This question comes up  frequently  on  the  OfflineIMAP  mailing  list
       <URL:http://lists.complete.org/offlineimap@complete.org/>.    You   can
       find      a      detailed       discussion       <URL:http://lists.com-
       plete.org/offlineimap@complete.org/2003/04/msg00012.html.gz>   of   the
       problem there.

   USE WITH MS EXCHANGE SERVER
       Several users have reported problems with Microsoft Exchange servers in
       conjunction  with  OfflineIMAP.   This generally seems to be related to
       the Exchange servers not properly following the IMAP standards.

       Mark  Biggers  has  posted  some   information   <URL:http://lists.com-
       plete.org/offlineimap@complete.org/2005/09/msg00011.html.gz>   to   the
       OfflineIMAP mailing list about how he made it work.

       Other users have indicated that older (5.5) releases of Exchange are so
       bad that they will likely not work at all.

       I  do  not have access to Exchange servers for testing, so any problems
       with it, if they can even be solved at  all,  will  require  help  from
       OfflineIMAP users to find and fix.

OTHER FREQUENTLY ASKED QUESTIONS
       There  are  some  other FAQs that might not fit into another section of
       the document, so they are discussed here.

       What platforms does OfflineIMAP run on?
              It should run on most platforms supported by Python,  which  are
              quite  a  few.   I  do not support Windows myself, but some have
              made it work there; see the FAQ entry for that platform.

       I'm using Mutt.  Other IMAP  sync  programs  require  me  to  use  "set
       maildir_trash=yes".  Do I need to do that with OfflineIMAP?
              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 this setting, in fact.

       I've upgraded and now OfflineIMAP crashes when I start it up!  Why?
              You need to upgrade  your  configuration  file.   See  [XRef  to
              UPGRADING.4.0] at the end of this manual.

       How do I specify the names of my folders?
              You  do  not  need to.  OfflineIMAP is smart enough to automati-
              cally figure out what folders are present on the IMAP server and
              synchronize  them.   You  can use the folderfilter and nametrans
              configuration file options to request certain folders and rename
              them as they come in if you like.

       How can I prevent certain folders from being synced?
              Use the folderfilter option in the configuration file.

       How can I add or delete a folder?
              OfflineIMAP  does not currently provide this feature, but if you
              create a new folder on the  IMAP  server,  it  will  be  created
              locally automatically.

       Are there any other warnings that I should be aware of?
              Yes; see the Notes section below.

       What is the mailbox name recorder (mbnames) for?
              Some  mail  readers,  such as Mutt, are not capable of automati-
              cally determining the names of your mailboxes.  OfflineIMAP  can
              help  these  programs  by  writing the names of the folders in a
              format  you  specify.   See  the  example  offlineimap.conf  for
              details.

       Can I synchronize multiple accounts with OfflineIMAP?
              Sure.   Just  name  them all in the accounts line in the general
              section of the configuration file, and add a per-account section
              for each one.

       Does OfflineIMAP support POP?
              No.  POP is not robust enough to do a completely reliable multi-
              machine synchronization like OfflineIMAP  can  do.   OfflineIMAP
              will not support it.

       Does OfflineIMAP support mailbox formats other than Maildir?
              Not  at  present.   There is no technical reason not to; just no
              demand yet.  Maildir is  a  superior  format  anyway.   However,
              OfflineIMAP  can  sync  between  two IMAP servers, and some IMAP
              servers support other formats.  You could install an IMAP server
              on your local machine and have OfflineIMAP sync to that.

       [technical] Why are your Maildir message filenames so huge?
              OfflineIMAP has two relevant principles: 1) never modifying your
              messages in any way and 2) ensuring 100%  reliable  synchroniza-
              tions.   In order to do a reliable sync, OfflineIMAP must have a
              way to uniquely identify each e-mail.  Three pieces of  informa-
              tion  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 dif-
              ferent  folder.   OfflineIMAP  stores the UID (U= number) and an
              md5sum of the foldername (FMD5= number) to facilitate this.

       What is the speed of OfflineIMAP's sync?
              OfflineIMAP versions 2.0 and above contain a multithreaded  sys-
              tem.   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  simultane-
              ously.   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:

              o 10 minutes with MacOS X Mail.app "manual cache"

              o 5 minutes with GNUS agent sync

              o 20 seconds with OfflineIMAP 1.x

              o 9 seconds with OfflineIMAP 2.x

              o 3 seconds with OfflineIMAP 3.x "cold start"

              o 2 seconds with OfflineIMAP 3.x "held connection"

       Can I use OfflineIMAP on Windows?
              These answers have been reported by OfflineIMAP users.  I do not
              run  OfflineIMAP  on Windows myself, so I can't directly address
              their accuracy.

              The basic answer is that it's possible and doesn't require hack-
              ing  OfflineIMAP  source  code.   However,  it's not necessarily
              trivial.  The information below is based in instructions submit-
              ted by Chris Walker.

              First,    you    must    run    OfflineIMAP    in   the   Cygwin
              <URL:http://www.cygwin.com/> environment.

              Next, you'll need to mount your Maildir directory in  a  special
              way.  There is information for doing that at
               <URL:http://barnson.org/node/view/295>.   That  site gives this
              example:

              mount -f -s -b -o managed "d:/tmp/mail" "/home/of/mail"


              That URL also has more details on making OfflineIMAP  work  with
              Windows.

CONFORMING TO
       o Internet Message Access Protocol version 4rev1 (IMAP 4rev1) as speci-
         fied in RFC2060 and RFC3501

       o CRAM-MD5 as specified in RFC2195

       o Maildir     as     specified     in     the      Maildir      manpage
         <URL:http://www.qmail.org/qmail-manual-html/man5/maildir.html>    and
         the qmail website <URL:http://cr.yp.to/proto/maildir.html>.

       o Standard Python 2.2.1 as implemented on POSIX-compliant systems.

NOTES
   DELETING LOCAL FOLDERS
       OfflineIMAP does a two-way synchronization.  That is,  if  you  make  a
       change  to  the mail on the server, it will be propagated 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)

   MULTIPLE INSTANCES
       OfflineIMAP  is not designed to have several instances (for instance, a
       cron job and an interactive  invocation)  run  over  the  same  mailbox
       simultaneously.   It  will  perform  a  check  on  startup and abort if
       another OfflineIMAP is already running.  If you need to  schedule  syn-
       chronizations,  please  use  the autorefresh settings rather than cron.
       Alternatively, you can set  a  separate  metadata  directory  for  each
       instance.

   COPYING MESSAGES BETWEEN FOLDERS
       Normally,  when you copy a message between folders or add a new message
       to a folder locally, OfflineIMAP will just do the  right  thing.   How-
       ever, sometimes this can be tricky -- if your IMAP server does not pro-
       vide  the  SEARCH  command,  or  does  not  return  something   useful,
       OfflineIMAP  cannot determine the new UID of the message.  So, in these
       rare instances, OfflineIMAP will upload the message to the IMAP  server
       and  delete  it  from  your local folder.  Then, on your next sync, the
       message will be re-downloaded with the proper UID.   OfflineIMAP  makes
       sure  that  the  message  was  properly uploaded before deleting it, so
       there should be no risk of data loss.

   USE WITH EVOLUTION
       OfflineIMAP can work with Evolution.  To do so,  first  configure  your
       OfflineIMAP  account  to have sep = / in its configuration.  Then, con-
       figure Evolution with  the  "Maildir-format  mail  directories"  server
       type.  For the path, you will need to specify the name of the top-level
       folder inside your OfflineIMAP storage location.  You're now set!

   USE WITH KMAIL
       At this time, I believe that OfflineIMAP with Maildirs is not  compati-
       ble  with  KMail.  KMail cannot work in any mode other than to move all
       messages out of all folders immediately, which (besides being  annoying
       and fundamentally broken) is incompatible with OfflineIMAP.

       However,  I  have  made  KMail  version 3 work well with OfflineIMAP by
       installing an IMAP server on my local machine, having OfflineIMAP  sync
       to that, and pointing KMail at the same server.

   MAILING LIST
       There is an OfflineIMAP mailing list available.  To subscribe, send the
       text "Subscribe" in the subject of a mail  to  offlineimap-request@com-
       plete.org.   To  post,  send  the  message to offlineimap@complete.org.
       Archives are available at
        <URL:http://lists.complete.org/offlineimap@complete.org/>.

   BUGS
       Reports of bugs should be sent via e-mail to  the  OfflineIMAP  mailing
       list  at  offlineimap at complete dot org.  Debian users are encouraged
       to instead use the Debian bug-tracking system.

UPGRADING TO 4.0
       If you are upgrading from a version of OfflineIMAP  prior  to  3.99.12,
       you  will  find  that  you  will  get errors when OfflineIMAP starts up
       (relating to ConfigParser or AccountHashGenerator) and  the  configura-
       tion  file.   This  is  because the config file format had to change to
       accommodate new features in 4.0.  Fortunately, it's  not  difficult  to
       adjust it to suit.

       First  thing  you  need to do is stop any running OfflineIMAP instance,
       making sure first that it's synced all your mail.   Then,  modify  your
       ~/.offlineimaprc  file.   You'll  need to split up each account section
       (make sure that it now starts with "Account ") into two Repository sec-
       tions  (one  for  the local side and another for the remote side.)  See
       the files offlineimap.conf.minimal and offlineimap.conf in the  distri-
       bution if you need more assistance.

       OfflineIMAP's  status  directory area has also changed.  Therefore, you
       should delete everything in ~/.offlineimap as well as your  local  mail
       folders.

       When  you  start  up OfflineIMAP 4.0, it will re-download all your mail
       from the server and then you can continue using it like normal.

COPYRIGHT
       OfflineIMAP, and  this  manual,  are  Copyright  (C)  2002,  2003  John
       Goerzen.

       This program is free software; you can redistribute it and/or modify it
       under the terms of the GNU General Public License as published  by  the
       Free  Software Foundation; either version 2 of the License, or (at your
       option) any later version.

       This program is distributed in the hope that it  will  be  useful,  but
       WITHOUT  ANY  WARRANTY;  without  even  the  implied  warranty  of MER-
       CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU  General
       Public License for more details.

       You should have received a copy of the GNU General Public License along
       with this program; if not, write to the Free Software Foundation, Inc.,
       59 Temple Place, Suite 330, Boston, MA  02111-1307 USA

       imaplib.py  comes  from  the  Python dev tree and is licensed under the
       GPL-compatible PSF license as stated  in  the  file  COPYRIGHT  in  the
       OfflineIMAP distribution.

AUTHOR
       OfflineIMAP,  its  libraries,  documentation,  and  all included files,
       except where noted, was written by John Goerzen <jgoerzen@complete.org>
       and copyright is held as stated in the COPYRIGHT section.

       OfflineIMAP may be downloaded, and information found, from its homepage
       <URL:http://software.complete.org/offlineimap>.

       OfflineIMAP may also be downloaded using Subversion.  Additionally, the
       distributed  tar.gz  may be updated with a simple "svn update" command;
       it is ready to go.  For information on getting OfflineIMAP with Subver-
       sion,     please     visit    the    complete.org    Subversion    page
       <URL:http://svn.complete.org/>.

SEE ALSO
       mutt(1), python(1)

HISTORY
       Detailed history may be found in the file ChangeLog in the  OfflineIMAP
       distribution.   Feature  and  bug  histories  may  be found in the file
       debian/changelog which, despite its name,  is  not  really  Debian-spe-
       cific.  This section provides a large overview.

       Development  on  OfflineIMAP began on June 18, 2002.  Version 1.0.0 was
       released three days later on June 21, 2002.  Point  releases  followed,
       including speed optimizations and some compatibility fixes.

       Version  2.0.0  was released on July 3, 2002, and represented the first
       time the synchronization became multithreaded and, to the  best  of  my
       knowledge,  the  first  multithreaded IMAP syncrhonizing application in
       existance.  The last 2.0.x release, 2.0.8, was made on July 9.

       Version 3.0.0 was released on July 11,  2002,  and  introduced  modular
       user interfaces and the first GUI interface for OfflineIMAP.  This man-
       ual also was  introduced  with  3.0.0,  along  with  many  command-line
       options.  Version 3.1.0 was released on July 21, adding the Noninterac-
       tive user interfaces, profiling support, and several  bugfixes.   3.2.0
       was  released  on  July  24,  adding  support for the Blinkenlights GUI
       interface.  OfflineIMAP entered maintenance mode for awhile, as it  had
       reached a feature-complete milestone in my mind.

       The  3.99.x  branch began in on October 7, 2002, to begin work for 4.0.
       The Curses.Blinkenlights interface was added in 3.99.6, and many archi-
       tectural changes were made.

       4.0.0  was released on July 18, 2003, including the ability to synchro-
       nize directly between two IMAP servers, the  first  re-architecting  of
       the  configuration file to refine the notion of an account, and the new
       Curses interface.



John Goerzen                   29 November 2006                 OFFLINEIMAP(1)