1IMAPSYNC(1) User Contributed Perl Documentation IMAPSYNC(1)
2
6 imapsync - Email IMAP tool for syncing, copying, migrating and
7 archiving email mailboxes between two imap servers, one way, and
8 without duplicates.
9
11 This documentation refers to Imapsync $Revision: 2.229 $
12
14 To synchronize the source imap account
15 "test1" on server "test1.lamiral.info" with password "secret1"
16 to the destination imap account
17 "test2" on server "test2.lamiral.info" with password "secret2"
18 do:
19 imapsync \
21 --host1 test1.lamiral.info --user1 test1 --password1 secret1 \
22 --host2 test2.lamiral.info --user2 test2 --password2 secret2
23
25 We sometimes need to transfer mailboxes from one imap server to one
26 another.
27 Imapsync command is a tool allowing incremental and recursive imap
29 transfers from one mailbox to another. If you don't understand the
30 previous sentence, it's normal, it's pedantic computer-oriented jargon.
31 All folders are transferred, recursively, meaning the whole folder
33 hierarchy is taken, all messages in them, and all message flags (\Seen
34 \Answered \Flagged etc.) are synced too.
35 Imapsync reduces the amount of data transferred by not transferring a
37 given message if it already resides on the destination side. Messages
38 that are on the destination side but not on the source side stay as
39 they are. See the --delete2 option to have strict sync and delete them.
40 How does imapsync know a message is already on both sides? Same
42 specific headers and the transfer is done only once. By default, the
43 identification headers are "Message-Id:" and "Received:" lines but this
44 choice can be changed with the --useheader option, most often a
45 duplicate problem is solved by using --useheader "Message-Id"
46 All flags are preserved, unread messages will stay unread, read ones
48 will stay read, deleted will stay deleted. In the IMAP protocol, a
49 deleted message is not deleted, it is marked \Deleted and can be
50 undeleted. Real destruction comes with the EXPUNGE or UIDEXPUNGE IMAP
51 commands.
52 You can abort the transfer at any time and restart it later, imapsync
54 works well with bad connections and interruptions, by design. On a
55 terminal hit Ctr-c twice within two seconds to abort the program. Hit
56 Ctr-c just once makes imapsync reconnect to both imap servers.
57 How do you know the sync is finished and well done? When imapsync ends
59 by itself it mentions it with lines like those:
60 Exiting with return value 0 (EX_OK: successful termination) 0/50 nb_errors/max_errors PID 301
62 Removing pidfile /tmp/imapsync.pid
63 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 )
64 If you don't have those lines it means that either the sync process is
66 still running (or eventually hanging indefinitely) or that it ended
67 without a whisper, a strong kill -9 on Linux for example.
68 If you have those final lines then it means the sync process is
70 properly finished. It may have encountered problems though.
71 A good synchronization is mentioned by some lines above the last ones,
73 especially those three lines:
74 The sync looks good, all 1745 identified messages in host1 are on host2.
76 There is no unidentified message on host1.
77 Detected 0 errors
78 Imapsync mentions the total sizes of both accounts at the beginning of
80 the sync and also at the end. Sometimes, even with a strict sync, those
81 total sizes differ, and sometimes they differ a lot. The difference is
82 not a good criterion to conclude the sync went wrong.
83 Why? That's because message sizes given by the imap servers are not
85 always accurate, they are not always the same as the actual message
86 sizes of the messages transferred by imapsync. Imapsync use the sizes
87 given by the imap servers to calculate the big total size. They can
88 differ. In the early days, Imapsync used the sizes of the messages as
89 one of the criteria to identify the messages, different sizes implied
90 different messages; but it was a mistake, the same message had
91 different sizes on both sides sometimes, depending on the imap servers.
92 Another explanation for a big total size difference is that Gmail
94 doesn't count the size of duplicate messages across folders twice,
95 while imapsync does.
96 A classical scenario is synchronizing a mailbox B from another mailbox
98 A where you just want to keep a strict copy of A in B. Strict meaning
99 all messages in A will be in B but no more.
100 For a strict synchronization, use the option --delete2. The option
102 --delete2 deletes the messages in the host2 folder B that are not in
103 the host1 folder A. If you also need to destroy host2 folders that are
104 not in host1 then use --delete2folders. See also --delete2foldersonly
105 and --delete2foldersbutnot to set up exceptions on folders to destroy.
106 INBOX will never be destroyed, it's a mandatory folder in IMAP so
107 imapsync doesn't even try to remove it.
108 A different scenario is to delete the messages from the source mailbox
110 after a successful transfer, it can be a good feature when migrating
111 mailboxes since messages will be only on one side. The source account
112 will only have messages that are not on the destination yet, ie,
113 messages that arrived after a sync or that failed to be transferred.
114 In that case, use the --delete1 option. Option --delete1 implies also
116 the option --expunge1 so all messages marked deleted on host1 will be
117 deleted. In IMAP protocol deleting a message does not delete it, it
118 marks it with the flag \Deleted, allowing an undelete. Expunging a
119 folder removes, definitively, all the messages marked as \Deleted in
120 this folder.
121 You can also decide to remove empty folders once all of their messages
123 have been transferred. Add --delete1emptyfolders to obtain this
124 behavior.
125 Imapsync is not adequate for maintaining two active imap accounts in
127 synchronization when the user plays independently on both sides. Use
128 offlineimap (written by John Goerzen) or mbsync (written by Michael R.
129 Elkins) for a 2 ways synchronization.
130
132 usage: imapsync [options]
133 The standard options are the six values forming the credentials. Three
135 values on each side are needed to login into the IMAP servers. These
136 six values are a hostname, a username, and a password, two times.
137 Here are the conventions used in the following descriptions of the
139 options:
140 str means a string
142 int means an integer number
143 flo means a float number
144 reg means a regular expression
145 cmd means a command
146 --dry : Makes imapsync do nothing for real; it just prints what
148 would be done without --dry.
149 OPTIONS/credentials
151 --host1 str : Source or "from" imap server.
152 --port1 int : Port to connect on host1.
153 Optional since default ports are the
154 well known ports imap/143 or imaps/993.
155 --user1 str : User to login on host1.
156 --password1 str : Password of user1.
157 --host2 str : "destination" imap server.
159 --port2 int : Port to connect on host2. Optional
160 --user2 str : User to login on host2.
161 --password2 str : Password of user2.
162 --showpasswords : Shows passwords on output instead of "MASKED".
164 Useful to restart a complete run by just reading
165 the command line used in the log,
166 or to debug passwords.
167 It's not a secure practice at all!
168 --passfile1 str : Password file for the user1. It must contain the
170 password on the first line. This option avoids showing
171 the password on the command line like --password1 does.
172 --passfile2 str : Password file for the user2.
173 You can also pass the passwords in the environment variables
175 IMAPSYNC_PASSWORD1 and IMAPSYNC_PASSWORD2. If you don't pass the user1
176 password via --password1 nor --passfile1 nor $IMAPSYNC_PASSWORD1 then
177 imapsync will prompt to enter the password on the terminal. Same thing
178 for user2 password.
179 OPTIONS/encryption
181 --nossl1 : Do not use a SSL connection on host1.
182 --ssl1 : Use a SSL connection on host1. On by default if possible.
183 --nossl2 : Do not use a SSL connection on host2.
185 --ssl2 : Use a SSL connection on host2. On by default if possible.
186 --notls1 : Do not use a TLS connection on host1.
188 --tls1 : Use a TLS connection on host1. On by default if possible.
189 --notls2 : Do not use a TLS connection on host2.
191 --tls2 : Use a TLS connection on host2. On by default if possible.
192 --debugssl int : SSL debug mode from 0 to 4.
194 --sslargs1 str : Pass any ssl parameter for host1 ssl or tls connection. Example:
196 --sslargs1 SSL_verify_mode=1 --sslargs1 SSL_version=SSLv3
197 See all possibilities in the new() method of IO::Socket::SSL
198 http://search.cpan.org/perldoc?IO::Socket::SSL#Description_Of_Methods
199 --sslargs2 str : Pass any ssl parameter for host2 ssl or tls connection.
200 See --sslargs1
201 OPTIONS/authentication
203 --authmech1 str : Auth mechanism to use with host1:
204 PLAIN, LOGIN, CRAM-MD5 etc. Use UPPERCASE.
205 --authmech2 str : Auth mechanism to use with host2. See --authmech1
206 --authuser1 str : User to auth with on host1 (admin user).
208 Avoid using --authmech1 SOMETHING with --authuser1.
209 --authuser2 str : User to auth with on host2 (admin user).
210 --proxyauth1 : Use proxyauth on host1. Requires --authuser1.
211 Required by Sun/iPlanet/Netscape IMAP servers to
212 be able to use an administrative user.
213 --proxyauth2 : Use proxyauth on host2. Requires --authuser2.
214 --authmd51 : Use MD5 authentication for host1.
216 --authmd52 : Use MD5 authentication for host2.
217 --domain1 str : Domain on host1 (NTLM authentication).
218 --domain2 str : Domain on host2 (NTLM authentication).
219 --oauthaccesstoken1 str : The access token to authenticate with OAUTH2.
221 It will be combined with the --user1 value to form the
222 string to pass with XOAUTH2 authentication.
223 The password given by --password1 or --passfile1
224 is ignored but needed on the command line.
225 Instead of the access token itself, the value can be a
226 file containing the access token on the first line.
227 If the value is a file, imapsync reads its first line
228 and take this line as the access token. The advantage
229 of the file is that if the access token changes then
230 imapsync can read it again when it needs to reconnect
231 during a run.
232 --oauthaccesstoken2 str : same thing as --oauthaccesstoken1
235 --oauthdirect1 str : The direct string to pass with XOAUTH2 authentication.
237 The password given by --password1 or --passfile1 and
238 the user given by --user1 are ignored but they are
239 needed to be on the command line. Consider it a bug.
240 --oauthdirect2 str : same thing as oauthdirect1
242 OPTIONS/folders
244 --folder str : Sync this folder.
245 --folder str : and this one, etc.
246 --folderrec str : Sync this folder recursively.
247 --folderrec str : and this one, etc.
248 --folderfirst str : Sync this folder first. Ex. --folderfirst "INBOX"
250 --folderfirst str : then this one, etc.
251 --folderlast str : Sync this folder last. --folderlast "[Gmail]/All Mail"
252 --folderlast str : then this one, etc.
253 --nomixfolders : Do not merge folders when host1 is case-sensitive
255 while host2 is not (like Exchange). Only the first
256 similar folder is synced. Example: with folders
257 "Sent", "SENT" and "sent" on host1, only "Sent"
258 will be synced to host2.
259 --skipemptyfolders : Empty host1 folders are not created on host2.
261 --include reg : Sync folders matching this regular expression
263 --include reg : or this one, etc.
264 If both --include --exclude options are used, then
265 include is done before.
266 --exclude reg : Skips folders matching this regular expression
267 Several folders to avoid:
268 --exclude 'fold1|fold2|f3' skips fold1, fold2 and f3.
269 --exclude reg : or this one, etc.
270 --automap : guesses folders mapping, for folders well known as
272 "Sent", "Junk", "Drafts", "All", "Archive", "Flagged".
273 --f1f2 str1=str2 : Force folder str1 to be synced to str2,
275 --f1f2 overrides --automap and --regextrans2.
276 Use several --f1f2 options to map several folders.
277 Option --f1f2 is a one to one only folder mapping,
278 str1 and str2 have to be full path folder names.
279 --subfolder2 str : Syncs the whole host1 folders hierarchy under the
281 host2 folder named str.
282 It does it internally by adding three
283 --regextrans2 options before all others.
284 Add --debug to see what's really going on.
285 --subfolder1 str : Syncs the host1 folders hierarchy which is under folder
287 str to the root hierarchy of host2.
288 It's the couterpart of a sync done by --subfolder2
289 when doing it in the reverse order.
290 Backup/Restore scenario:
291 Use --subfolder2 str for a backup to the folder str
292 on host2. Then use --subfolder1 str for restoring
293 from the folder str, after inverting
294 host1/host2 user1/user2 values.
295 --subscribed : Transfers subscribed folders.
298 --subscribe : Subscribe to the folders transferred on the
299 host2 that are subscribed on host1. On by default.
300 --subscribeall : Subscribe to the folders transferred on the
301 host2 even if they are not subscribed on host1.
302 --prefix1 str : Remove prefix str to all destination folders,
304 usually "INBOX." or "INBOX/" or an empty string "".
305 imapsync guesses the prefix if host1 imap server
306 does not have NAMESPACE capability. So this option
307 should not be used most of the time.
308 --prefix2 str : Add prefix to all host2 folders. See --prefix1
309 --sep1 str : Host1 separator. This option should not be used
311 most of the time.
312 Imapsync gets the separator from the server itself,
313 by using NAMESPACE, or it tries to guess it
314 from the folders listing (it counts
315 characters / . \\ \ in folder names and choose the
316 more frequent, or finally / if nothing is found.
317 --sep2 str : Host2 separator. See --sep1
318 --regextrans2 reg : Apply the whole regex to each destination folders.
320 --regextrans2 reg : and this one. etc.
321 When you play with the --regextrans2 option, first
322 add also the safe options --dry --justfolders
323 Then, when happy, remove --dry for a run, then
324 remove --justfolders for the next ones.
325 Have in mind that --regextrans2 is applied after
326 the automatic prefix and separator inversion.
327 For examples see:
328 https://imapsync.lamiral.info/FAQ.d/FAQ.Folders_Mapping.txt
329 OPTIONS/folders sizes
331 --nofoldersizes : Do not calculate the size of each folder at the
332 beginning of the sync. Default is to calculate them.
333 --nofoldersizesatend: Do not calculate the size of each folder at the
334 end of the sync. Default is to calculate them.
335 --justfoldersizes : Exit after having printed the initial folder sizes.
336 OPTIONS/tmp
338 --tmpdir str : Where to store temporary files and subdirectories.
339 Will be created if it doesn't exist.
340 Default is system specific, Unix is /tmp but
341 /tmp is often too small and deleted at reboot.
342 --tmpdir /var/tmp should be better.
343 --pidfile str : The file where imapsync pid is written,
345 it can be dirname/filename complete path.
346 The default name is imapsync.pid in tmpdir.
347 --pidfilelocking : Abort if pidfile already exists. Useful to avoid
349 concurrent transfers on the same mailbox.
350 OPTIONS/log
352 --nolog : Turn off logging on file
353 --logfile str : Change the default log filename (can be dirname/filename).
354 --logdir str : Change the default log directory. Default is LOG_imapsync/
355 The default logfile name is for example
357 LOG_imapsync/2019_12_22_23_57_59_532_user1_user2.txt
359 where:
361 2019_12_22_23_57_59_532 is nearly the date of the start
363 YYYY_MM_DD_HH_MM_SS_mmm
364 year_month_day_hour_minute_second_millisecond
365 and user1 user2 are the --user1 --user2 values.
367 OPTIONS/messages
369 --skipmess reg : Skips messages matching the regex.
370 Example: 'm/[\x80-\xff]/' # to avoid 8bits messages.
371 --skipmess is applied before --regexmess
372 --skipmess reg : or this one, etc.
373 --skipcrossduplicates : Avoid copying messages that are already copied
375 in another folder, good from Gmail to XYZ when
376 XYZ is not also Gmail.
377 Activated with --gmail1 unless --noskipcrossduplicates
378 --debugcrossduplicates : Prints which messages (UIDs) are skipped with
380 --skipcrossduplicates and in what other folders
381 they are.
382 --pipemess cmd : Apply this cmd command to each message content
384 before the copy.
385 --pipemess cmd : and this one, etc.
386 With several --pipemess, the output of each cmd
387 command (STDOUT) is given to the input (STDIN)
388 of the next command.
389 For example,
390 --pipemess cmd1 --pipemess cmd2 --pipemess cmd3
391 is like a Unix pipe:
392 "cat message | cmd1 | cmd2 | cmd3"
393 --disarmreadreceipts : Disarms read receipts (host2 Exchange issue)
395 --regexmess reg : Apply the whole regex to each message before transfer.
397 Example: 's/\000/ /g' # to replace null characters
398 by spaces.
399 --regexmess reg : and this one, etc.
400 --truncmess int : truncates messages when their size exceed the int
402 value, specified in bytes. Good to sync too big
403 messages or to "suppress" attachments.
404 Have in mind that this way, messages become
405 uncoherent somehow.
406 OPTIONS/labels
408 Gmail present labels as folders in imap. Imapsync can accelerate the
409 sync by syncing X-GM-LABELS, it will avoid to transfer messages when
410 they are already on host2 in another folder.
411 --synclabels : Syncs also Gmail labels when a message is copied to host2.
413 Activated by default with --gmail1 --gmail2 unless
414 --nosynclabels is added.
415 --resynclabels : Resyncs Gmail labels when a message is already on host2.
417 Activated by default with --gmail1 --gmail2 unless
418 --noresynclabels is added.
419 For Gmail syncs, see also:
421 https://imapsync.lamiral.info/FAQ.d/FAQ.Gmail.txt
422 OPTIONS/flags
424 If you encounter flag problems see also:
425 https://imapsync.lamiral.info/FAQ.d/FAQ.Flags.txt
426 --regexflag reg : Apply the whole regex to each flags list.
428 Example: 's/"Junk"//g' # to remove "Junk" flag.
429 --regexflag reg : then this one, etc.
430 --resyncflags : Resync flags for already transferred messages.
432 On by default.
433 --noresyncflags : Do not resync flags for already transferred messages.
434 May be useful when a user has already started to play
435 with its host2 account.
436 --filterbuggyflags : Filter flags known to be buggy and generators of errors
438 "BAD Invalid system flag" or "NO APPEND Invalid flag list".
439 OPTIONS/deletions
441 --delete1 : Deletes messages on host1 server after a successful
442 transfer. Option --delete1 has the following behavior:
443 it marks messages as deleted with the IMAP flag
444 \Deleted, then messages are really deleted with an
445 EXPUNGE IMAP command. If expunging after each message
446 slows down too much the sync then use
447 --noexpungeaftereach to speed up, expunging will then be
448 done only twice per folder, one at the beginning and
449 one at the end of a folder sync.
450 --expunge1 : Expunge messages on host1 just before syncing a folder.
452 Expunge is done per folder.
453 Expunge aims is to really delete messages marked deleted.
454 An expunge is also done after each message copied
455 if option --delete1 is set (unless --noexpungeaftereach).
456 --noexpunge1 : Do not expunge messages on host1.
458 --delete1emptyfolders : Deletes empty folders on host1, INBOX excepted.
460 Useful with --delete1 since what remains on host1
461 is only what failed to be synced.
462 --delete2 : Delete messages in the host2 account that are not in
464 the host1 account. Useful for backup or pre-sync.
465 --delete2 implies --uidexpunge2
466 --delete2duplicates : Deletes messages in host2 that are duplicates in host2.
468 Works only without --useuid since duplicates are
469 detected with an header part of each message.
470 NB: --delete2duplicates is far less violent than --delete2
471 since it removes only duplicates.
472 --delete2folders : Delete folders in host2 that are not in host1.
474 For safety, first try it like this, it is safe:
475 --delete2folders --dry --justfolders --nofoldersizes
476 and see what folders will be deleted.
477 --delete2foldersonly reg : Delete only folders matching the regex reg.
479 Example: --delete2foldersonly "/^Junk$|^INBOX.Junk$/"
480 This option activates --delete2folders
481 --delete2foldersbutnot reg : Do not delete folders matching the regex rex.
483 Example: --delete2foldersbutnot "/Tasks$|Contacts$|Foo$/"
484 This option activates --delete2folders
485 --noexpunge2 : Do not expunge messages on host2.
487 --nouidexpunge2 : Do not uidexpunge messages on the host2 account
488 that are not on the host1 account.
489 OPTIONS/dates
491 If you encounter problems with dates, see also:
492 https://imapsync.lamiral.info/FAQ.d/FAQ.Dates.txt
493 --syncinternaldates : Sets the internal dates on host2 as the same as host1.
495 Turned on by default. Internal date is the date
496 a message arrived on a host (Unix mtime usually).
497 --idatefromheader : Sets the internal dates on host2 as same as the
498 ones in "Date:" headers.
499 OPTIONS/message selection
501 --maxsize int : Skip messages larger (or equal) than int bytes
502 --minsize int : Skip messages smaller (or equal) than int bytes
503 --maxage int : Skip messages older than int days.
505 final stats (skipped) don't count older messages
506 see also --minage
507 --minage int : Skip messages newer than int days.
508 final stats (skipped) don't count newer messages
509 You can do (+ zone are the messages selected):
510 past|----maxage+++++++++++++++>now
511 past|+++++++++++++++minage---->now
512 past|----maxage+++++minage---->now (intersection)
513 past|++++minage-----maxage++++>now (union)
514 --search str : Selects only messages returned by this IMAP SEARCH
516 command. Applied on both sides.
517 For a complete set of what can be search see
518 https://imapsync.lamiral.info/FAQ.d/FAQ.Messages_Selection.txt
519 --search1 str : Same as --search but for selecting host1 messages only.
521 --search2 str : Same as --search but for selecting host2 messages only.
522 So --search CRIT equals --search1 CRIT --search2 CRIT
523 --noabletosearch : Makes --minage and --maxage options use the internal
525 dates given by a FETCH imap command instead of the
526 "Date:" header. Internal date is the arrival date
527 in the mailbox.
528 --noabletosearch equals --noabletosearch1 --noabletosearch2
529 --noabletosearch1 : Like --noabletosearch but for host1 only.
531 --noabletosearch2 : Like --noabletosearch but for host2 only.
532 --maxlinelength int : skip messages with a line length longer than int bytes.
534 RFC 2822 says it must be no more than 1000 bytes but
535 real life servers and email clients do more.
536 --useheader str : Use this header to compare messages on both sides.
539 Example: "Message-Id" or "Received" or "Date".
540 --useheader str and this one, etc.
541 --syncduplicates : Sync also duplicates. Off by default.
543 --usecache : Use cache to speed up next syncs. Off by default.
545 --nousecache : Do not use cache. Caveat: --useuid --nousecache creates
546 duplicates on multiple runs.
547 --useuid : Use UIDs instead of headers as a criterion to recognize
549 messages. Option --usecache is then implied unless
550 --nousecache is used.
551 OPTIONS/miscellaneous
553 --syncacls : Synchronizes acls (Access Control Lists).
554 Acls in IMAP are not standardized, be careful
555 since one acl code on one side may signify something
556 else on the other one.
557 --nosyncacls : Does not synchronize acls. This is the default.
558 --addheader : When a message has no headers to be identified,
560 --addheader adds a "Message-Id" header,
561 like "Message-Id: 12345@imapsync", where 12345
562 is the imap UID of the message on the host1 folder.
563 Useful to sync folders "Sent" or "Draft".
564 OPTIONS/debugging
566 --debug : Debug mode.
567 --debugfolders : Debug mode for the folders part only.
568 --debugcontent : Debug content of the messages transferred. Huge output.
569 --debugflags : Debug mode for flags.
570 --debugimap1 : IMAP debug mode for host1. Very verbose.
571 --debugimap2 : IMAP debug mode for host2. Very verbose.
572 --debugimap : IMAP debug mode for host1 and host2. Twice very verbose.
573 --debugmemory : Debug mode showing memory consumption after each copy.
574 --errorsmax int : Exit when int number of errors is reached. Default is 50.
576 --tests : Run local non-regression tests. Exit code 0 means all ok.
578 --testslive : Run a live test with test1.lamiral.info imap server.
579 Useful to check the basics. Needs internet connection.
580 --testslive6 : Run a live test with ks6ipv6.lamiral.info imap server.
581 Useful to check the ipv6 connectivity. Needs internet.
582 OPTIONS/specific
584 --gmail1 : sets --host1 to Gmail and other options. See FAQ.Gmail.txt
585 --gmail2 : sets --host2 to Gmail and other options. See FAQ.Gmail.txt
586 --office1 : sets --host1 to Office365 and other options. See FAQ.Office365.txt
588 --office2 : sets --host2 to Office365 and other options. See FAQ.Office365.txt
589 --exchange1 : sets options for Exchange. See FAQ.Exchange.txt
591 --exchange2 : sets options for Exchange. See FAQ.Exchange.txt
592 --domino1 : sets options for Domino. See FAQ.Domino.txt
594 --domino2 : sets options for Domino. See FAQ.Domino.txt
595 OPTIONS/behavior
597 --timeout1 flo : Connection timeout in seconds for host1.
598 Default is 120 and 0 means no timeout at all.
599 --timeout2 flo : Connection timeout in seconds for host2.
600 Default is 120 and 0 means no timeout at all.
601 Caveat, under CGI context, you may encounter a timeout
603 from the webserver, killing imapsync and the imap connections.
604 See the document INSTALL.OnlineUI.txt and search
605 for "Timeout" for how to deal with this issue.
606 --keepalive1 : https://metacpan.org/pod/Mail::IMAPClient#Keepalive
608 Some firewalls and network gears like to timeout connections
609 prematurely if the connection sits idle.
610 This option enables SO_KEEPALIVE on the host1 socket.
611 --keepalive1 is on by default since imapsync release 2.169
612 Use --nokeepalive1 to disable it.
613 --keepalive2 : Same as --keepalive2 but for host2.
615 Use --nokeepalive2 to disable it.
616 --maxmessagespersecond flo : limits the average number of messages
618 transferred per second.
619 --maxbytespersecond int : limits the average transfer rate per second.
621 --maxbytesafter int : starts --maxbytespersecond limitation only after
622 --maxbytesafter amount of data transferred.
623 --maxsleep flo : do not sleep more than int seconds.
625 On by default, 2 seconds max, like --maxsleep 2
626 --abort : terminates a previous call still running.
628 It uses the pidfile to know what process to abort.
629 --exitwhenover int : Stop syncing and exits when int total bytes
631 transferred is reached.
632 --version : Print only the software version.
634 --noreleasecheck : Do not check for any new imapsync release.
635 --releasecheck : Check for new imapsync release.
636 it's an http request to
637 http://imapsync.lamiral.info/prj/imapsync/VERSION
638 --emailreport1 : Put the email final report in host1 INBOX
640 --emailreport2 : Put the email final report in host2 INBOX
641 --noemailreport1 : Do not put the email final report in host1 INBOX
643 --noemailreport2 : Do not put the email final report in host2 INBOX
644 --noid : Do not send/receive IMAP "ID" command to imap servers.
646 --justconnect : Just connect to both servers and print useful
648 information. Need only --host1 and --host2 options.
649 Obsolete since "imapsync --host1 imaphost" alone
650 implies --justconnect
651 --justlogin : Just login to both host1 and host2 with users
653 credentials, then exit.
654 --justfolders : Do only things about folders (ignore messages).
656 --help : print this help.
658 Example: to synchronize imap account "test1" on "test1.lamiral.info"
660 to imap account "test2" on "test2.lamiral.info"
661 with test1 password "secret1"
662 and test2 password "secret2"
663 imapsync \
665 --host1 test1.lamiral.info --user1 test1 --password1 secret1 \
666 --host2 test2.lamiral.info --user2 test2 --password2 secret2
667
669 You can use --passfile1 instead of --password1 to mention the password
670 since it is safer. With --password1 option, on Linux, any user on your
671 host can see the password by using the 'ps auxwwww' command. Using a
672 variable (like IMAPSYNC_PASSWORD1) is also dangerous because of the 'ps
673 auxwwwwe' command. So, saving the password in a well protected file
674 (600 or rw-------) is the best solution.
675 Imapsync activates ssl or tls encryption by default, if possible.
677 What detailed behavior is under this "if possible"?
679 Imapsync activates ssl if the well known port imaps port (993) is open
681 on the imap servers. If the imaps port is closed then it open a normal
682 (clear) connection on port 143 but it looks for TLS support in the
683 CAPABILITY list of the servers. If TLS is supported then imapsync goes
684 to encryption with STARTTLS.
685 If the automatic ssl and the tls detections fail then imapsync will not
687 protect against sniffing activities on the network, especially for
688 passwords.
689 If you want to force ssl or tls just use --ssl1 --ssl2 or --tls1 --tls2
691 See also the document FAQ.Security.txt in the FAQ.d/ directory or at
693 https://imapsync.lamiral.info/FAQ.d/FAQ.Security.txt
694
696 Imapsync will exit with a 0 status (return code) if everything went
697 good. Otherwise, it exits with a non-zero status. That's classical
698 Unix behavior. Here is the list of the exit code values (an integer
699 between 0 and 255). In Bourne Shells, this exit code value can be
700 retrieved within the variable value "$?" if you read it just after the
701 imapsync call.
702 The names reflect their meaning:
704 EX_OK => 0 ; #/* successful termination */
706 EX_USAGE => 64 ; #/* command line usage error */
707 EX_NOINPUT => 66 ; #/* cannot open input */
708 EX_UNAVAILABLE => 69 ; #/* service unavailable */
709 EX_SOFTWARE => 70 ; #/* internal software error */
710 EXIT_CATCH_ALL => 1 ; # Any other error
711 EXIT_BY_SIGNAL => 6 ; # Should be 128+n where n is the sig_num
712 EXIT_BY_FILE => 7 ;
713 EXIT_PID_FILE_ERROR => 8 ;
714 EXIT_CONNECTION_FAILURE => 10 ;
715 EXIT_TLS_FAILURE => 12 ;
716 EXIT_AUTHENTICATION_FAILURE => 16 ;
717 EXIT_SUBFOLDER1_NO_EXISTS => 21 ;
718 EXIT_WITH_ERRORS => 111 ;
719 EXIT_WITH_ERRORS_MAX => 112 ;
720 EXIT_OVERQUOTA => 113 ;
721 EXIT_ERR_APPEND => 114 ;
722 EXIT_ERR_FETCH => 115 ;
723 EXIT_ERR_CREATE => 116 ;
724 EXIT_ERR_SELECT => 117 ;
725 EXIT_TRANSFER_EXCEEDED => 118 ;
726 EXIT_ERR_APPEND_VIRUS => 119 ;
727 EXIT_TESTS_FAILED => 254 ; # Like Test::More API
728 EXIT_CONNECTION_FAILURE_HOST1 => 101 ;
729 EXIT_CONNECTION_FAILURE_HOST2 => 102 ;
730 EXIT_AUTHENTICATION_FAILURE_USER1 => 161 ;
731 EXIT_AUTHENTICATION_FAILURE_USER2 => 162 ;
732
734 Imapsync is free, open, public but not always gratis software cover by
735 the NOLIMIT Public License, now called NLPL. See the LICENSE file
736 included in the distribution or just read the following simple sentence
737 as it IS the license text:
738 "No limits to do anything with this work and this license."
740 In case it is not long enough, I repeat:
742 "No limits to do anything with this work and this license."
744 Look at https://imapsync.lamiral.info/LICENSE
746
748 Gilles LAMIRAL <gilles@lamiral.info>
749 Good feedback is always welcome. Bad feedback is very often welcome.
751 Gilles LAMIRAL earns his living by writing, installing, configuring and
753 sometimes teaching free, open, and often gratis software. Imapsync used
754 to be "always gratis" but now it is only "often gratis" because
755 imapsync is sold by its author, your servitor, a good way to maintain
756 and support free open public software tools over decades.
757
759 See https://imapsync.lamiral.info/FAQ.d/FAQ.Reporting_Bugs.txt
760
762 See https://imapsync.lamiral.info/S/imapservers.shtml
763
765 If you have many mailboxes to migrate think about a little shell
766 program. Write a file called file.txt (for example) containing users
767 and passwords. The separator used in this example is ';'
768 The file.txt file contains:
770 user001_1;password001_1;user001_2;password001_2
772 user002_1;password002_1;user002_2;password002_2
773 user003_1;password003_1;user003_2;password003_2
774 user004_1;password004_1;user004_2;password004_2
775 user005_1;password005_1;user005_2;password005_2 ...
776 On Unix the shell program can be:
778 { while IFS=';' read u1 p1 u2 p2; do
780 imapsync --host1 imap.side1.org --user1 "$u1" --password1 "$p1" \
781 --host2 imap.side2.org --user2 "$u2" --password2 "$p2" ...
782 done ; } < file.txt
783 On Windows the batch program can be:
785 FOR /F "tokens=1,2,3,4 delims=; eol=#" %%G IN (file.txt) DO imapsync ^
787 --host1 imap.side1.org --user1 %%G --password1 %%H ^
788 --host2 imap.side2.org --user2 %%I --password2 %%J ...
789 The ... have to be replaced by nothing or any imapsync option. Welcome
791 in shell or batch programming !
792 You will find already written scripts at
794 https://imapsync.lamiral.info/examples/
795
797 Imapsync works under any Unix with Perl.
798 Imapsync works under most Windows (2000, XP, Vista, Seven, Eight, Ten
800 and all Server releases 2000, 2003, 2008 and R2, 2012 and R2, 2016)
801 as a standalone binary software called imapsync.exe, usually launched
802 from a batch file in order to avoid always typing the options. There
803 is also a 32bit binary called imapsync_32bit.exe
804 Imapsync works under OS X as a standalone binary software called
806 imapsync_bin_Darwin
807 Purchase latest imapsync at
809 https://imapsync.lamiral.info/
810 You'll receive a link to a compressed tarball called
812 imapsync-x.xx.tgz where x.xx is the version number.
813 Untar the tarball where you want (on Unix):
814 tar xzvf imapsync-x.xx.tgz
816 Go into the directory imapsync-x.xx and read the INSTALL file.
818 As mentioned at https://imapsync.lamiral.info/#install
819 the INSTALL file can also be found at
820 https://imapsync.lamiral.info/INSTALL.d/INSTALL.ANY.txt
821 It is now split in several files for each system
822 https://imapsync.lamiral.info/INSTALL.d/
823
825 There is no specific configuration file for imapsync, everything is
826 specified by the command line parameters and the default behavior.
827
829 Feel free to hack imapsync as the NOLIMIT license permits it.
830
832 See also https://imapsync.lamiral.info/S/external.shtml
833 for a better up to date list.
834 List verified on Friday July 1, 2021.
836 imapsync: https://github.com/imapsync/imapsync (this is an imapsync copy, sometimes delayed, with --noreleasecheck by default since release 1.592, 2014/05/22)
838 imap_tools: https://web.archive.org/web/20161228145952/http://www.athensfbc.com/imap_tools/. The imap_tools code is now at https://github.com/andrewnimmo/rick-sanders-imap-tools
839 imaputils: https://github.com/mtsatsenko/imaputils (very old imap_tools fork)
840 Doveadm-Sync: https://wiki2.dovecot.org/Tools/Doveadm/Sync ( Dovecot sync tool )
841 davmail: http://davmail.sourceforge.net/
842 offlineimap: http://offlineimap.org/
843 fdm: https://github.com/nicm/fdm
844 mbsync: http://isync.sourceforge.net/
845 mailsync: http://mailsync.sourceforge.net/
846 mailutil: https://www.washington.edu/imap/ part of the UW IMAP toolkit. (well, seems abandoned now)
847 imaprepl: https://bl0rg.net/software/ http://freecode.com/projects/imap-repl/
848 imapcopy (Pascal): http://www.ardiehl.de/imapcopy/
849 imapcopy (Java): https://code.google.com/archive/p/imapcopy/
850 imapsize: http://www.broobles.com/imapsize/
851 migrationtool: http://sourceforge.net/projects/migrationtool/
852 imapmigrate: http://sourceforge.net/projects/cyrus-utils/
853 larch: https://github.com/rgrove/larch (derived from wonko_imapsync, good at Gmail)
854 wonko_imapsync: http://wonko.com/article/554 (superseded by larch)
855 pop2imap: http://www.linux-france.org/prj/pop2imap/ (I wrote that too)
856 exchange-away: http://exchange-away.sourceforge.net/
857 SyncBackPro: http://www.2brightsparks.com/syncback/sbpro.html
858 ImapSyncClient: https://github.com/ridaamirini/ImapSyncClient
859 MailStore: https://www.mailstore.com/en/products/mailstore-home/
860 mnIMAPSync: https://github.com/manusa/mnIMAPSync
861 imap-upload: http://imap-upload.sourceforge.net/ (A tool for uploading a local mbox file to IMAP4 server)
862 imapbackup: https://github.com/rcarmo/imapbackup (A Python script for incremental backups of IMAP mailboxes)
863 BitRecover email-backup 99 USD, 299 USD https://www.bitrecover.com/email-backup/.
864 ImportExportTools: https://addons.thunderbird.net/en-us/thunderbird/addon/importexporttools/ ImportExportTools for Mozilla Thunderbird by Paolo Kaosmos. ImportExportTools does not do IMAP.
865 rximapmail: https://sourceforge.net/projects/rximapmail/
866 CodeTwo: https://www.codetwo.com/ but CodeTwo does imap source to Office365 only.
867
869 I initially wrote imapsync in July 2001 because an enterprise, called
870 BaSystemes, paid me to install a new imap server without losing huge
871 old mailboxes located in a far away remote imap server, accessible by
872 an often broken low-bandwidth ISDN link.
873 I had to verify every mailbox was well transferred, all folders, all
875 messages, without wasting bandwidth or creating duplicates upon
876 resyncs. The imapsync design was made with the beautiful rsync command
877 in mind.
878 Imapsync started its life as a patch of the copy_folder.pl script. The
880 script copy_folder.pl comes from the Mail-IMAPClient-2.1.3 perl module
881 tarball source (more precisely in the examples/ directory of the Mail-
882 IMAPClient tarball).
883 So many changes happened since then that I wonder if it remains any
885 lines of the original copy_folder.pl in imapsync source code.
886perl v5.38.0 2023-07-20 IMAPSYNC(1)