Man Linux: Main Page and Category List


       mbsync - synchronize IMAP4 and Maildir mailboxes


       mbsync [options ...] {{channel[:box[{,|\n}...]]|group} ...|-a}


       mbsync  is  a  command  line  application which synchronizes mailboxes;
       currently Maildir and IMAP4 mailboxes  are  supported.   New  messages,
       message  deletions  and  flag  changes can be propagated both ways; the
       operation set can be selected in a fine-grained manner.
       Synchronization is based on unique message identifiers  (UIDs),  so  no
       identification  conflicts  can  occur  (as  opposed  to some other mail
       synchronizers).  OTOH, mbsync is susceptible to  UID  validity  changes
       (that  should  never  happen,  but  see "Compatibility" in the README).
       Synchronization state is kept in one local text file per mailbox  pair;
       multiple replicas of a mailbox can be maintained.


       -c, --config file
              Read  configuration from file.  By default, the configuration is
              read from ~/.mbsyncrc.

       -a, --all
              Select all configured channels. Any channel/group specifications
              on the command line are ignored.

       -l, --list
              Don’t  synchronize  anything,  but  list  all  mailboxes  in the
              selected channels and exit.

       -C[m][s], --create[-master|-slave]
              Override any Create options from the config file. See below.

       -X[m][s], --expunge[-master|-slave]
              Override any Expunge options from the config file. See below.

       {-n|-N|-d|-f|-0|-F}, {--new|--renew|--delete|--flags|--noop|--full}
       {-L|-H}[n][N][d][f], {--pull|--push}[-new|-renew|-delete|-flags]

              Override any Sync options from the config file. See below.

       -h, --help
              Display a summary of command line options.

       -v, --version
              Display version information.

       -V, --verbose
              Enable verbose mode, which displays the IMAP4 network traffic.

       -D, --debug
              Enable printing debug information.

       -q, --quiet
              Suppress informational messages.  If specified  twice,  suppress
              warning messages as well.


       The  configuration  file  is mandatory; mbsync will not run without it.
       Lines starting with a hash  mark  (#)  are  comments  and  are  ignored
       entirely.   Configuration  items  are  keywords followed by one or more
       arguments; arguments containing  spaces  must  be  enclosed  in  double
       quotes (").  All keywords (including those used as arguments) are case-
       insensitive.  There are a few  global  options,  the  rest  applies  to
       particular sections.  Sections are started by a section keyword and are
       terminated by an empty line or end of file.  Every section  defines  an
       object with a an identifier unique within that object class.

       There  are  two  basic  object  classes:  Stores  and Channels. A Store
       defines a collection of mailboxes; basically a folder, either local  or
       remote.   A Channel connects two Stores, describing the way the two are
       There are two auxiliary object classes: Accounts and Groups. An Account
       describes  the connection part of remote Stores, so a server connection
       can be shared between multiple  Stores.  A  Group  aggregates  multiple
       Channels to save typing on the command line.

   All Stores
       These options can be used in all supported Store types.
       In  this context, the term "remote" describes the second Store within a
       Channel, and not necessarily a remote server.
       The special mailbox INBOX exists in every Store; its physical  location
       in the file system is Store type specific.

       Path path
              The  location  of  the  Store in the (server’s) file system.  If
              this is no absolute path, the  reference  point  is  Store  type
              specific.   This  string  is  prepended  to  the  mailbox  names
              addressed in this Store, but is not  considered  part  of  them;
              this  is  important  for Patterns in the Channels section.  Note
              that you must append a slash if you want to  specify  an  entire
              directory.  (Default: "")

       MaxSize size[k|m][b]
              Messages  larger  than  that  will  not  be propagated into this
              Store.  This is useful  for  weeding  out  messages  with  large
              attachments.   K  and  M  can be appended to the size to specify
              KiBytes resp.  MeBytes instead  of  bytes.  B  is  accepted  but
              superflous.    If  size  is  0,  the  maximum  message  size  is
              unlimited.  (Default: 0)

       MapInbox mailbox
              Create a virtual mailbox (relative to Path), which is backed  by
              the  INBOX.  Makes  sense  in  conjunction  with Patterns in the
              Channels section.

       Trash mailbox
              Specifies a mailbox (relative to Path) to copy deleted  messages
              to  prior  to expunging. See INHERENT PROBLEMS below.  (Default:

       TrashNewOnly yes|no
              When trashing, copy only not yet propagated messages. This makes
              sense if the remote Store has a Trash as well (with TrashNewOnly
              no).  (Default: no)

       TrashRemoteNew yes|no
              When  expunging  the  remote  Store,  copy  not  yet  propagated
              messages  to  this  Store’s  Trash.  When using this, the remote
              Store does not need an own Trash at all, yet  all  messages  are
              archived.  (Default: no)

   Maildir Stores
       The reference point for relative Paths is $HOME.

       As mbsync needs UIDs, but no standardized UID storage scheme exists for
       Maildir, mbsync supports two schemes, each with its pros and cons.
       The native scheme is stolen from the latest Maildir patches to c-client
       and  is therefore compatible with pine. The UID validity is stored in a
       file named .uidvalidity; the UIDs are encoded in the file names of  the
       The  alternative  scheme  is  based  on  the  UID mapping used by isync
       versions 0.8 and 0.9.x. The invariant parts of the file  names  of  the
       messages   are   used   as   keys   into   a  Berkeley  database  named
       .isyncuidmap.db, which holds the UID validity as well.
       The  native  scheme  is  faster,  more   space   efficient,   endianess
       independent and "human readable", but will be disrupted if a message is
       copied from another mailbox without getting a new file name; this would
       result  in  duplicated UIDs sooner or later, which in turn results in a
       UID validity change,  making  synchronization  fail.   The  alternative
       scheme  would  fail  if  a  MUA changed a message’s file name in a part
       mbsync considers invariant; this would  be  interpreted  as  a  message
       deletion and a new message, resulting in unnecessary traffic.
       Mutt is known to work fine with both schemes.
       Use mdconvert to convert mailboxes from one scheme to the other.

       MaildirStore name
              Define  the  Maildir  Store  name,  opening  a  section  for its

       AltMap yes|no
              Use the alternative UID storage scheme  for  mailboxes  in  this
              Store.   This  does  not affect mailboxes that do already have a
              UID storage scheme; use mdconvert to change it.  (Default: no)

       Inbox path
              The location of  the  INBOX.  This  is  not  relative  to  Path.
              (Default: ~/Maildir)

   IMAP4 Accounts
       IMAPAccount name
              Define  the  IMAP4  Account  name,  opening  a  section  for its

       Host host
              Specify the DNS name or IP address of the IMAP server.

       Port port
              Specify the TCP port number of the IMAP server.   (Default:  143
              for IMAP, 993 for IMAPS)

       User username
              Specify  the  login  name on the IMAP server.  (Default: current
              local user)

       Pass password
              Specify the password for username on the IMAP server.  Note that
              this option is NOT required.  If no password is specified in the
              configuration file, mbsync will prompt you for it.

       Tunnel command
              Specify a command to run to establish a connection  rather  than
              opening  a  TCP  socket.  This allows you to run an IMAP session
              over  an  SSH  tunnel,  for  example.   This  makes  most  other
              IMAPAccount options superflous.

       RequireCRAM yes|no
              If  set  to yes, mbsync will abort the connection if no CRAM-MD5
              authentication is possible.  (Default: no)

       UseIMAPS yes|no
              If set to yes, the default for Port is changed to 993 and mbsync
              will  start  SSL  negotiation immediately after establishing the
              connection to the server.
              Note that modern servers support SSL on the  regular  IMAP  port
              143 via the STARTTLS extension, which will be used automatically
              by default.

       RequireSSL yes|no
              mbsync will abort the connection if a TLS/SSL session cannot  be
              established with the IMAP server.  (Default: yes)

       CertificateFile path
              File  containing  X.509  CA  certificates  used to verify server
              identities.  This option is mandatory if SSL is  used.  See  SSL
              CERTIFICATES below.

       UseSSLv2 yes|no
              Use SSLv2 for communication with the IMAP server over SSL?
              Note  that  this  option  is  deprecated  for  security reasons.
              (Default: no)

       UseSSLv3 yes|no
              Use SSLv3 for communication  with  the  IMAP  server  over  SSL?
              (Default: no)

       UseTLSv1 yes|no
              Use  TLSv1  for  communication  with  the  IMAP server over SSL?
              (Default: yes)

   IMAP Stores
       The reference point for relative Paths is whatever the server likes  it
       to  be;  probably  the  user’s  $HOME or $HOME/Mail on that server. The
       location of  INBOX  is  up  to  the  server  as  well  and  is  usually

       IMAPStore name
              Define   the  IMAP4  Store  name,  opening  a  section  for  its

       Account account
              Specify which IMAP4 Account  to  use.  Instead  of  defining  an
              Account  and referencing it here, it is also possible to specify
              all the Account options directly in the Store’s section  -  this
              makes sense if an Account is used for one Store only anyway.

       UseNamespace yes|no
              Selects  whether  the server’s first "personal" NAMESPACE should
              be prefixed to mailbox names. Disabling  this  makes  sense  for
              some  broken IMAP servers.  This option is meaningless if a Path
              was specified.  (Default: yes)

       Channel name
              Define the Channel name, opening a section for its parameters.

       {Master|Slave} :store:[mailbox]
              Specify the Master resp. Slave Store to  be  connected  by  this
              Channel.   If mailbox is omitted, INBOX is assumed.  The mailbox
              specification can be overridden by Patterns, which in  turn  can
              be  overridden by a mailbox list in a Channel reference (a Group
              specification or the command line).

       Pattern[s] [!]pattern ...
              Instead of synchronizing only one mailbox pair, synchronize  all
              mailboxes  that  match the pattern(s). The mailbox names are the
              same on both Master and  Slave.  Patterns  are  IMAP4  patterns,
              i.e.,  *  matches anything and % matches anything up to the next
              hierarchy delimiter. Prepending !  to  a  pattern  makes  it  an
              exclusion.   Multiple  patterns  can  be  specified  (either  by
              supplying  multiple  arguments  or  by  using  Pattern  multiple
              times);     later    matches    take    precedence.     Example:
              "Patterns % !Trash"

       MaxSize size[k|m][b]
              Analogous to the homonymous option in the  Stores  section,  but
              applies  equally  to  Master  and Slave. Note that this actually
              modifies the Stores, so take care  not  to  provide  conflicting
              settings if you use the Stores in multiple Channels.

       MaxMessages count
              Sets  the  maximum  number  of  messages  to  keep in each Slave
              mailbox.  This is useful for mailboxes where you keep a complete
              archive on the server, but want to mirror only the last messages
              (for instance, for mailing lists).  The messages that  were  the
              first to arrive in the mailbox (independently of the actual date
              of the message)  will  be  deleted  first.   Messages  that  are
              flagged  (marked  as  important) and recent messages will not be
              automatically deleted.  If count is 0,  the  maximum  number  of
              messages is unlimited (Default: 0).

       Sync {None|[Pull] [Push] [New] [ReNew] [Delete] [Flags]|Full}
              Select the synchronization operation(s) to perform:
              Pull - propagate changes from Master to Slave.
              Push - propagate changes from Slave to Master.
              New - propagate newly appeared messages.
              ReNew   -  previously  refused  messages  are  re-evaluated  for
              propagation.  Useful after flagging  affected  messages  in  the
              source Store or enlarging MaxSize in the destination Store.
              Delete  -  propagate  message  deletions.  This  applies only to
              messages that  are  actually  gone,  i.e.,  were  expunged.  The
              affected  messages  in  the  remote  Store are marked as deleted
              only, i.e., they won’t be really deleted  until  that  Store  is
              Flags  -  propagate flag changes. Note that Deleted/Trashed is a
              flag as well; this is particularily interesting if you use  mutt
              with the maildir_trash option.
              All  (--full  on  the command line) - all of the above.  This is
              the global default.
              None (--noop on the command line) -  don’t  propagate  anything.
              Useful if you want to expunge only.

              Pull  and Push are direction flags, while New, ReNew, Delete and
              Flags are type flags. The  two  flag  classes  make  up  a  two-
              dimensional  matrix  (a  table).  Its  cells  are the individual
              actions to perform. There are two styles of asserting the cells:
              In  the  first style, the flags select entire rows/colums in the
              matrix. Only the cells which are selected both horizontally  and
              vertically  are  asserted.   Specifying no flags from a class is
              like  specifying  all  flags  from  this  class.   For  example,
              "Sync Pull New Flags"  will  propagate  new  messages  and  flag
              changes from the Master to  the  Slave,  "Sync New Delete"  will
              propagate   message   arrivals  and  deletions  both  ways,  and
              "Sync Push" will propagate all changes from  the  Slave  to  the
              In  the second style, direction flags are concatenated with type
              flags; every compound flag immediately asserts  a  cell  in  the
              matrix.   In  addition  to  at  least  one  compound  flag,  the
              individual flags can be used as well,  but  as  opposed  to  the
              first   style,  they  immediately  assert  all  cells  in  their
              respective          row/column.           For           example,
              "Sync PullNew PullDelete Push"  will  propagate message arrivals
              and deletions from the Master to the Slave and any changes  from
              the  Slave to the Master.  Note that it is not allowed to assert
              a   cell   in   two   ways,   e.g.    "Sync PullNew Pull"    and
              "Sync PullNew Delete Push" induce error messages.

       Create {None|Master|Slave|Both}
              Automatically  create  missing  mailboxes [on the Master/Slave].
              Otherwise print an error message and skip that mailbox pair if a
              mailbox does not exist.  (Global default: None)

       Expunge {None|Master|Slave|Both}
              Permanently remove all messages [on the Master/Slave] marked for
              deletion.  (Global default: None)

       Sync, Create and Expunge can be used outside any section for  a  global
       effect. The global settings are overridden by Channel-specific options,
       which in turn are overridden by command line switches.

       SyncState {*|path}
              Set the location of this Channel’s synchronization state  files.
              *  means  that  the  state  should  be  saved  in  a  file named
              .mbsyncstate in the Slave mailbox itself; this has the advantage
              that  you  needn’t  to care for the state file if you delete the
              mailbox, but it works only with  Maildir  mailboxes,  obviously.
              Otherwise  this  is  interpreted  as  a string to prepend to the
              Slave mailbox name to make up a complete path.
              This option can be used outside any section for a global effect.
              In  this  case  the  appended string is made up according to the
              pattern :master:master-box_:slave:slave-box.
              (Global default: ~/.mbsync/).

       Group name [channel[:box[,...]]] ...
              Define the Group name, opening a  section  for  its  parameters.
              Note  that  even  though Groups have an own namespace, they will
              "hide" Channels with the same name on the command line.
              One or more Channels can be specified on the same line.
              If you supply one or more boxes to a channel, they will be  used
              instead  of  what  is  specified in the Channel. The same can be
              done on the command line, except that there newlines can be used
              as mailbox name separators as well.

       Channel[s] channel[:box[,...]] ...
              Add  the  specified  channels  to  the group. This option can be
              specified multiple times within a Group.


       [to be done]


       Changes done after mbsync has retrieved the message list  will  not  be
       synchronised until the next time mbsync is invoked.

       Using  Trash  on  IMAP  Stores bears a race condition: messages will be
       lost if they are marked as deleted after the message list was retrieved
       but  before  the  mailbox  is expunged. There is no risk as long as the
       IMAP mailbox is not simultaneously accessed by mbsync and another  mail


              Default configuration file

              Directory containing synchronization state files


       mdconvert(1), isync(1), mutt(1), maildir(5)

       Up to date information on mbsync can be found at


       Written by Michael R. Elkins <>,
       rewritten and maintained by Oswald Buddenhagen <>,
       contributions by Theodore Y. Ts’o <>.

                                  2004 Mar 27                        mbsync(1)