Imapsync

NAME

imapsync - Email IMAP tool for syncing, copying, migrating and archiving
email mailboxes between two imap servers, one way, and without
duplicates.

VERSION

This documentation refers to Imapsync $Revision: 2.229 $

USAGE

 To synchronize the source imap account
   "test1" on server "test1.lamiral.info" with password "secret1"
 to the destination imap account
   "test2" on server "test2.lamiral.info" with password "secret2"
 do:

  imapsync \
   --host1 test1.lamiral.info --user1 test1 --password1 secret1 \
   --host2 test2.lamiral.info --user2 test2 --password2 secret2

DESCRIPTION

We sometimes need to transfer mailboxes from one imap server to one
another.

Imapsync command is a tool allowing incremental and recursive imap
transfers from one mailbox to another. If you don't understand the
previous sentence, it's normal, it's pedantic computer-oriented jargon.

All folders are transferred, recursively, meaning the whole folder
hierarchy is taken, all messages in them, and all message flags (\Seen
\Answered \Flagged etc.) are synced too.

Imapsync reduces the amount of data transferred by not transferring a
given message if it already resides on the destination side. Messages
that are on the destination side but not on the source side stay as they
are. See the --delete2 option to have strict sync and delete them.

How does imapsync know a message is already on both sides? Same specific
headers and the transfer is done only once. By default, the
identification headers are "Message-Id:" and "Received:" lines but this
choice can be changed with the --useheader option, most often a
duplicate problem is solved by using --useheader "Message-Id"

All flags are preserved, unread messages will stay unread, read ones
will stay read, deleted will stay deleted. In the IMAP protocol, a
deleted message is not deleted, it is marked \Deleted and can be
undeleted. Real destruction comes with the EXPUNGE or UIDEXPUNGE IMAP
commands.

You can abort the transfer at any time and restart it later, imapsync
works well with bad connections and interruptions, by design. On a
terminal hit Ctr-c twice within two seconds to abort the program. Hit
Ctr-c just once makes imapsync reconnect to both imap servers.

How do you know the sync is finished and well done? When imapsync ends
by itself it mentions it with lines like those:

  Exiting with return value 0 (EX_OK: successful termination) 0/50 nb_errors/max_errors PID 301
  Removing pidfile /tmp/imapsync.pid
  Log file is LOG_imapsync/2020_11_17_15_59_22_761_test1_test2.txt ( to change it, use --logfile filepath ; or use --nolog to turn off logging )

If you don't have those lines it means that either the sync process is
still running (or eventually hanging indefinitely) or that it ended
without a whisper, a strong kill -9 on Linux for example.

If you have those final lines then it means the sync process is properly
finished. It may have encountered problems though.

A good synchronization is mentioned by some lines above the last ones,
especially those three lines:

  The sync looks good, all 1745 identified messages in host1 are on host2.
  There is no unidentified message on host1.
  Detected 0 errors

Imapsync mentions the total sizes of both accounts at the beginning of
the sync and also at the end. Sometimes, even with a strict sync, those
total sizes differ, and sometimes they differ a lot. The difference is
not a good criterion to conclude the sync went wrong.

Why? That's because message sizes given by the imap servers are not
always accurate, they are not always the same as the actual message
sizes of the messages transferred by imapsync. Imapsync use the sizes
given by the imap servers to calculate the big total size. They can
differ. In the early days, Imapsync used the sizes of the messages as
one of the criteria to identify the messages, different sizes implied
different messages; but it was a mistake, the same message had different
sizes on both sides sometimes, depending on the imap servers.

Another explanation for a big total size difference is that Gmail
doesn't count the size of duplicate messages across folders twice, while
imapsync does.

A classical scenario is synchronizing a mailbox B from another mailbox A
where you just want to keep a strict copy of A in B. Strict meaning all
messages in A will be in B but no more.

For a strict synchronization, use the option --delete2. The option
--delete2 deletes the messages in the host2 folder B that are not in the
host1 folder A. If you also need to destroy host2 folders that are not
in host1 then use --delete2folders. See also --delete2foldersonly and
--delete2foldersbutnot to set up exceptions on folders to destroy. INBOX
will never be destroyed, it's a mandatory folder in IMAP so imapsync
doesn't even try to remove it.

A different scenario is to delete the messages from the source mailbox
after a successful transfer, it can be a good feature when migrating
mailboxes since messages will be only on one side. The source account
will only have messages that are not on the destination yet, ie,
messages that arrived after a sync or that failed to be transferred.

In that case, use the --delete1 option. Option --delete1 implies also
the option --expunge1 so all messages marked deleted on host1 will be
deleted. In IMAP protocol deleting a message does not delete it, it
marks it with the flag \Deleted, allowing an undelete. Expunging a
folder removes, definitively, all the messages marked as \Deleted in
this folder.

You can also decide to remove empty folders once all of their messages
have been transferred. Add --delete1emptyfolders to obtain this
behavior.

Imapsync is not adequate for maintaining two active imap accounts in
synchronization when the user plays independently on both sides. Use
offlineimap (written by John Goerzen) or mbsync (written by Michael R.
Elkins) for a 2 ways synchronization.

OPTIONS

 usage: imapsync [options]

The standard options are the six values forming the credentials. Three
values on each side are needed to login into the IMAP servers. These six
values are a hostname, a username, and a password, two times.

Here are the conventions used in the following descriptions of the
options:

 str means a string
 int means an integer number
 flo means a float number
 reg means a regular expression
 cmd means a command

 --dry               : Makes imapsync do nothing for real; it just prints what
                       would be done without --dry.

OPTIONS/credentials

 --host1        str  : Source or "from" imap server.
 --port1        int  : Port to connect on host1.
                       Optional since default ports are the
                       well known ports imap/143 or imaps/993.
 --user1        str  : User to login on host1.
 --password1    str  : Password of user1.

 --host2        str  : "destination" imap server.
 --port2        int  : Port to connect on host2. Optional
 --user2        str  : User to login on host2.
 --password2    str  : Password of user2.

 --showpasswords     : Shows passwords on output instead of "MASKED".
                       Useful to restart a complete run by just reading
                       the command line used in the log,
                       or to debug passwords.
                       It's not a secure practice at all!

 --passfile1    str  : Password file for the user1. It must contain the
                       password on the first line. This option avoids showing
                       the password on the command line like --password1 does.
 --passfile2    str  : Password file for the user2.

You can also pass the passwords in the environment variables
IMAPSYNC_PASSWORD1 and IMAPSYNC_PASSWORD2. If you don't pass the user1
password via --password1 nor --passfile1 nor $IMAPSYNC_PASSWORD1 then
imapsync will prompt to enter the password on the terminal. Same thing
for user2 password.

OPTIONS/encryption

 --nossl1            : Do not use a SSL connection on host1.
 --ssl1              : Use a SSL connection on host1. On by default if possible.

 --nossl2            : Do not use a SSL connection on host2.
 --ssl2              : Use a SSL connection on host2. On by default if possible.

 --notls1            : Do not use a TLS connection on host1.
 --tls1              : Use a TLS connection on host1. On by default if possible.

 --notls2            : Do not use a TLS connection on host2.
 --tls2              : Use a TLS connection on host2. On by default if possible.

 --debugssl     int  : SSL debug mode from 0 to 4.

 --sslargs1     str  : Pass any ssl parameter for host1 ssl or tls connection. Example:
                       --sslargs1 SSL_verify_mode=1 --sslargs1 SSL_version=SSLv3
                       See all possibilities in the new() method of IO::Socket::SSL
                       http://search.cpan.org/perldoc?IO::Socket::SSL#Description_Of_Methods
 --sslargs2     str  : Pass any ssl parameter for host2 ssl or tls connection.
                       See --sslargs1

OPTIONS/authentication

 --authmech1    str  : Auth mechanism to use with host1:
                       PLAIN, LOGIN, CRAM-MD5 etc. Use UPPERCASE.
 --authmech2    str  : Auth mechanism to use with host2. See --authmech1

 --authuser1    str  : User to auth with on host1 (admin user).
                       Avoid using --authmech1 SOMETHING with --authuser1.
 --authus