% $Id: TUTORIAL.t2t,v 1.3 2014/10/08 08:49:29 gilles Exp gilles $

= Tutorial for imapsync =

== Introduction ==

Three Internet protocols are used to access almost all email accounts: 
POP, IMAP, HTTP.

The oldest one is POP, Post Office Protocol, it allows only 
one main box, also called INBOX. 
The second protocol is IMAP, Internet Message Access Protocol, which allows
a hierarchy of mailboxes also called folders, it also allows concurrent accesses, 
tagging with flags, search by many criterium like date, subject, size etc.
The third protocol is HTTP, HyperText Transfer Protocol, via webmails.
Webmails often offer the same features than imap servers and, 
since webmails background is often an imap server,
a parallel access via IMAP.


Software imapsync is a command line tool to 
copy, migrate, backup or synchronize IMAP mailboxes.


Command line means imapsync is not graphical, it is textual, 
you have to type characters on your keyboard. 
Your fingers will not suffer anyway because 
I wrote examples nearly ready to go. 
Most of the time you only have to change values 
and adapt them to your context.

Do not be afraid, the mouse will not be forsaken. 
You can still use the mouse to launch an editor, 
select/copy/paste complete examples 
and run the little script you edit with a doubleclick.

Imapsync runs on Unix or Windows.
It is because imapsync is written in the Perl language
and thanks to the Perl creators Perl runs everywhere.
Outside imapsync life is different; 
Historically Windows came after Unix and the marvelous designers 
of this old time decided it would be very cool 
to not share the same syntax for doing the same things. 
Thanks guys, great thinking!

To avoid you to learn by headaches a system you do not master 
I will give all examples in both worlds, Unix and Windows. 
Macintosh users are in the Unix world now but do not tell them, 
it can hurt the olders.


== Conventions ==

Imapsync has many options but you can ignore most of them 
and still make great transfers.

In this documentation I write all the examples as a complete example. 
In order to simplify the reading or the printing,
the command is written on several lines. 
It could be written on one single line;
if you prefer the whole command on one line then 
just remove the last character of each line, 
it is the "\" character on Unix examples 
or the "^" character on Windows examples.

For example, on Unix

```
  imapsync \
     --host1 imap.truc.org \
     --user1 foo \
     --password1 secret1 \
     ...
```
is equivalent to
```
  imapsync --host1 imap.truc.org --user1 foo --password1 secret1 ...
```

and on Windows
```
  imapsync ^
     --host1 imap.truc.org ^
     --user1 foo ^
     --password1 secret1 ^
     ...
```
is equivalent to
```
  imapsync --host1 imap.truc.org --user1 foo --password1 secret1 ...
```