Migrate e-mail over IMAP with PHP

Switching groupware platforms can be a challenging project. Many vendors provide tools to make the transition as easy as possible and it also exists many generic tools for IMAP synchronization. Unfortunately I was let down by both our groupware vendor tools and the most common generic tools. That is why I wrote this guide for how to migrate email from one IMAP platform to another by using PHP IMAP module.

In my life as Marketing Techie I face new challenges every day. Recently I faced a migration from Cyrus IMAP to Novell Groupwise and the project techies failed to automatically migrate the emails and the folder trees between my IMAP accounts. Unfortunately neither the migration tools provided by Novell for Groupwise nor the most common generic tools saved me from what was looking like a time consuming copy and past job in the mail client.

Background knowledge and technology

I wanted to make a simple script for moving multi-level IMAP folder structures including e-mails from one server to another. Experience tells me that this is a generic job, and can be used in several situations, like:

  • Migrating from one groupware platform to another
  • Move from one hosting provider to another
  • Backup your e-mail

In this guide I will base upon the following knowledge level and technology:

  • Basic PHP development knowledge
  • PHP 5.2 with IMAP and mbstring modules
  • Access to PHP-CLI for running the script
  • Text editor for development
  • IMAP connection information about your source and target servers

The basics of the IMAP migration code

When migrating thousands of emails it’s unrealistic to expect that not a single email is going to fail during the transport. You may even lose the connection while the script is working it’s way trough your emails. For those of you who already migrated from one IMAP server to another IMAP server manually, know that you will frequently need to handle errors manually. To avoid interruptions in the migration I added two functions:

  • In case of an error, log the error to /tmp/imap_migration_log including the email subject and folder, and continue
  • Keep track on finished folder in /tmp/imap_migration_history if we need to restart

$target_connectionstring = “{}”;
$target_username = “user1”;
$target_password = “password1”;
$target_folder = ‘migration’;

$source_connectionstring = “{}INBOX”;
$source_username = “user2”;
$source_password = “password2”;

This part is the essential setting to make the script work. In fact these are all the variables that you need to modify. At first glance the connection strings may look confusing so I would recommend that you read and understand how imap_open connect to IMAP servers on first.

The “target_folder” is the folder where your IMAP tree will be migrated to. It’s recommended to create an own target folder in order to prevent problems with already existing folders such as Sent items, Drafts, Inbox etc.

IMAP synchronisation output

In order to run the script you will need to access a shell / terminal. Simply go into the directory were the script is located and write “php imapmigration.php”. An example of the script output is shown below. Each dot (.) represent a successfully transferred e-mail while each pipe (|) represent an error in the transfer.

Working on /Archive/Cusomters/
111 mails to migrate: …………………………………………………………………..|………………………………………………….|……………………….|…………………….|…..

The full IMAP migration code

You can download the code here.

Experience and issues

As many of my other guides, this one was written to provide you with a some ideas on how to resolve a problem using technology. However this script has some issues that worth to mention and that may need to be improved.

  • If you stop the script while it’s working on a folder it will create duplicated copies of the emails previously transferred to that folder when the script is restarted.
  • The script use a fair amount of memory, about the double of your largest e-mail.
  • All email flags are removed and the emails get status as “Open”

Help to move, synchronise or migrate IMAP ?

Please use the feedback form below if you need help to transfer e-mails from one IMAP server to another.

Related links