HOW TO: Using IMAPSync to Transfer mail from server to server

sneader

Well-Known Member
Aug 21, 2003
1,168
53
178
La Crosse, WI
cPanel Access Level
Root Administrator
There is an active feature request to have cPanel add a tool to help migrate IMAP Mailboxes from a non-cPanel server to a cPanel server. This is very important if you are trying to help a customer move to your cPanel hosting service, from a non-cPanel server. You can read (and vote on) the feature request at: Migrate IMAP mailbox to cPanel

Our company has been very successful in using a command-line tool called IMAPSync to accomplish this task. I was asked in the feature request thread to document how to install and use this tool, so here goes:

About the tool:
imapsync is a tool authored by French developer Gilles Lamiral.
It is not free, but is a reasonable €50 EUR for lifetime license.
Full "professional support" available for an extra €50 EUR.
Official website: Official imapsync migration tool ( release 1.727 ) -- a LOT of info here, so go and read it!
NOTE: You can keep running this script over and over. It will skip messages that already exist on the new server. So, you can copy once, then change MX/DNS, then run it again later, to catch any messages that came in after the first run.​

Check to see if you have imapsync installed already:
Issue the command: imapsync -v
If you have it installed, it will report back the version number.
If you do not have it installed, of course it will just result in an error.
Install imapsync:
imapsync requires the epel repo. On my cPanel servers, I don't have the epel repo installed or enabled, so my instructions will show how to do that also. Your mileage may vary.
  1. Make a directory to store the download (optional): mkdir /root/imapsync
  2. Move into the directory (optional): cd /root/imapsync
  3. Download the epel repo: wget https://dl.fedoraproject.org/pub/epel/epel-release-latest-6.noarch.rpm
  4. Install epel repo: yum install epel-release-latest-6.noarch.rpm
  5. Install imapsync: yum install imapsync
  6. Disable epel repo: Edit file /etc/yum.repos.d/epel.repo and change all references of enabled=1 to enabled=0
  7. Edit your Firewall to allow outbound TCP connections on ports 143 (non-SSL IMAP) and/or 993 (SSL IMAP)
Upgrade imapsync: (for future reference)
Because we have disabled the epel repo, you won't get auto updates of imapsync. To upgrade imapsync:
  1. Enable epel repo: Edit file /etc/yum.repos.d/epel.repo and change all references of enabled=0 to enabled=1
  2. Upgrade imapsync: yum update imapsync
  3. Disable epel repo: Edit file /etc/yum.repos.d/epel.repo and change all references of enabled=1 to enabled=0
Use imapsync to transfer one IMAP mailbox: (basic example)
Here is a basic script to transfer one mailbox, without using any of the many available option flags. This will use non-SSL port 143.

Code:
/usr/bin/imapsync \
  --host1 oldserver.example.com --user1 [email protected] --password1  "somepass" \
  --host2 newserver.example.com --user2 [email protected] --password2 "somepass"
Use imapsync to transfer one IMAP mailbox to GMAIL, with extra flags/options:
GMail requires that you use the SSL port 993. This example forces port 993, uses one of GMail's IPs as the server (using a FQDN didn't work for some reason), does 100 messages at a time (GMail needs this), and does some other things that I can't remember now (do your own research -- just sharing this example which consistently works great for me to move a customer's mail from one of our cPanel servers to a GMail mailbox:

Code:
/usr/bin/imapsync --no-modules_version --showpasswords --addheader \
  --host1 cpanel.example.com --user1 [email protected] --password1 'somepass' \
  --host2 173.194.194.108 --user2 [email protected] --password2 'somepass' \
  --port2 993 --ssl1 --ssl2 --split1 100 --split2 100 --syncinternaldates \
  --noauthmd5 --authmech1 LOGIN --authmech2 LOGIN --allowsizemismatch --useheader Message-ID
Move MULTIPLE mailboxes at a time with imapsync:
Moving multiple IMAP mailboxes at a time is similar to the examples above, with the difference being that you create a text file of email addresses and passwords and then you run your move script against that list.

First, create a file called list1.txt and put in a list of emails and passwords. the format is email address on old server, password on old server, email address on new server, password on new server. Each item is separated by a semi-colon.

Code:
[email protected];oldserverpass1;[email protected];newserverpass1
[email protected]example.com;oldserverpass2;[email protected];newserverpass2
[email protected];oldserverpass3;[email protected];newserverpass3
Next, create your script that will look like the single mailbox moving one-liner, but will read in your list of emails and passwords and process them one at a time:

Code:
{ while IFS=';' read  u1 p1 u2 p2
    do
        { echo "$u1" | egrep "^#" ; } > /dev/null && continue # this skips commented lines in list1.txt
        echo "==== Syncing user $u1 to user $u2 ===="

        imapsync --host1 oldserver.example.com --addheader --user1  "$u1" --password1 "$p1" \
                 --host2 newserver.example.com --user2 "$u2" --password2 "$p2"

        echo "==== End syncing user $u1 to user $u2 ===="

        echo
    done
} < list1.txt
Again, you will adjust this to have the right servers, perhaps changing the port number, or adding any of the many flags/options that could help you with your particular situation (read the docs!)

What I do is to put a # in front of each line except the first, to comment them all out but the first one, to test things out. Then remove the #'s and run the whole thing.
Troubleshooting:

Each time you run imapsync, it creates a log in a folder called LOG_imapsync, which will be in the same folder as where you downloaded and installed imapsync.

To change it, there are option flags (yes, read the docs!) use --logfile filepath or use --nolog to turn off logging
I hope this helps!

- Scott
 

cPanelMichael

Administrator
Staff member
Apr 11, 2011
47,911
2,234
363
Hello Scott,

Thanks for taking the time to write up this tutorial!
 

krembo99

Active Member
May 30, 2013
34
2
8
cPanel Access Level
Root Administrator
Thanks, really great info here .
I really really hope that cPanel will consider integrating this tool and an interface for it like in the mentioned feature request .
It is really a must today ( 4 years after the request was made ) when IMAP is quasi-standard ..

Some questions :

Does the above process leave the original box intact ?

In my scenario, I have a bad host / panel , about 8 years old , with not many mailboxes or mails ( 2-3 boxes , few hundreds mails ).
I would like to use the following workflow :

1- Create a new account in cpanel
2 - move the mailboxes and mails
3 - Check the mails manually on the ( new ) WHM/ Cpanel account
3 - Only after that to transfer the DNS / Domain registration to new server.

Would that be a viable workflow with this tool ?
Does the tool works the same for sub.domains ? ( [email protected] )
I assume yes (because it is imap ) , but just to make sure - the SENT folder is also transfered ?
 

cPanelMichael

Administrator
Staff member
Apr 11, 2011
47,911
2,234
363
Hello @krembo99,

You shouldn't encounter any issues with the workflow you described. The messages on the source server are not deleted unless you specify the "--delete" flag in the command. Email accounts associated with subdomains should work the same way as regular domain names.

Thank you.
 

lorio

Well-Known Member
Feb 25, 2004
298
14
168
cPanel Access Level
Root Administrator