Imapsync copies messages and folders from one IMAP mailbox to another. It is useful when moving email between hosting providers, control panels, or mail platforms while keeping the source mailbox available for a final catch-up pass.
This guide explains how to migrate email with imapsync on Ubuntu 24.04 or EL9 without exposing mailbox passwords in the process list or shell history. It also covers testing, folder mapping, repeat runs, MX cutover, and verification.
What Imapsync Copies
- IMAP folders and their hierarchy
- Email messages
- Common message flags such as read, answered, and flagged
- New messages during repeat one-way synchronization
Imapsync does not move DNS, MX records, contacts, calendars, rules, aliases, signatures, distribution lists, or account settings. Plan those separately. It is a one-way transfer tool, not a safe two-way sync for users actively changing both mailboxes.
Plan the Mail Migration
- Inventory every mailbox, alias, shared mailbox, forwarding rule, group, and catch-all.
- Check source size, message count, folder names, quotas, and largest messages.
- Create destination accounts with enough quota.
- Confirm both providers allow IMAP access and the required authentication method.
- Lower DNS TTL before the planned MX change.
- Run a pilot mailbox and verify it with the user.
- Perform an initial bulk copy while old mail remains live.
- Change MX and related mail DNS.
- Run one or more final incremental passes.
- Keep the source read-only or available until acceptance and rollback periods end.
Check Provider Authentication First
Many providers block normal account passwords for IMAP. You may need an application password, administrator migration credential, or OAuth2 access token. Gmail and Microsoft 365 have provider-specific OAuth procedures in the imapsync documentation. Do not disable multi-factor authentication just to make an old password work.
Install Imapsync
Imapsync changes regularly and its installation differs by operating system. Check the current upstream INSTALL.d instructions and release before running a production migration. Avoid downloading an old script from an unrelated blog or gist.
A source installation begins with the official repository:
sudo apt update sudo apt install -y git make cpanminus git clone https://github.com/imapsync/imapsync.git cd imapsync less INSTALL less Makefile
Install the dependencies listed for your current Ubuntu or EL release, run the upstream tests, and use its documented install target. On EL9, check EPEL for a maintained package, but compare its version with upstream before migrating. Confirm what will run:
command -v imapsync imapsync --version imapsync --help | less
Never Put Mail Passwords in the Command
The old article placed real-looking passwords after --password1 and --password2. On Linux, another local user may see command arguments with ps, and the shell may save them in history. Imapsync recommends protected password files.
install -m 600 /dev/null /tmp/source-imap.pass install -m 600 /dev/null /tmp/destination-imap.pass nano /tmp/source-imap.pass nano /tmp/destination-imap.pass chmod 600 /tmp/source-imap.pass /tmp/destination-imap.pass
Put only the password or app password on the first line of each file. Store long-term secrets in an approved secret manager; these temporary files should be deleted after the migration. Environment variables are also visible in some process-inspection situations and are not the best substitute.
Test Network and TLS
openssl s_client -connect imap.old.example:993 -servername imap.old.example -brief openssl s_client -connect imap.new.example:993 -servername imap.new.example -brief
Use hostnames that match trusted certificates, not raw IP addresses. Imapsync can auto-detect encryption, but forcing IMAPS for both sides prevents an accidental clear connection when detection changes.
Test Login Without Copying Messages
imapsync \ --host1 imap.old.example --port1 993 --ssl1 \ --user1 [email protected] --passfile1 /tmp/source-imap.pass \ --host2 imap.new.example --port2 993 --ssl2 \ --user2 [email protected] --passfile2 /tmp/destination-imap.pass \ --justlogin
If login fails, check the username format, IMAP setting, application password/OAuth requirement, source-IP restrictions, TLS hostname, and provider logs. Avoid repeated attempts that lock the account.
Review Folders and Sizes
imapsync \ --host1 imap.old.example --port1 993 --ssl1 \ --user1 [email protected] --passfile1 /tmp/source-imap.pass \ --host2 imap.new.example --port2 993 --ssl2 \ --user2 [email protected] --passfile2 /tmp/destination-imap.pass \ --justfoldersizes
Compare the result with destination quota and provider limits. Folder names such as Sent, Sent Items, Junk, Spam, and Archive may differ. Imapsync’s --automap option can guess common mappings, but verify the result for a pilot account.
Run the First Mailbox Migration
mkdir -m 700 -p "$HOME/imapsync-logs" imapsync \ --host1 imap.old.example --port1 993 --ssl1 \ --user1 [email protected] --passfile1 /tmp/source-imap.pass \ --host2 imap.new.example --port2 993 --ssl2 \ --user2 [email protected] --passfile2 /tmp/destination-imap.pass \ --automap \ --logfile "$HOME/imapsync-logs/user-example.log"
Do not add --delete1, --delete2, expunge, or folder-deletion options to a first migration. The normal behavior is additive: messages already identified at the destination are not copied again, and destination-only messages remain.
Check the Result
A successful process exits with status 0, but also read the summary. Imapsync reports whether identified source messages exist on the destination and how many errors occurred.
echo $? tail -n 50 "$HOME/imapsync-logs/user-example.log"
- Compare folder counts and sizes.
- Open old and recent messages with attachments.
- Check Sent, Drafts, Junk, Archive, nested folders, and flags.
- Search for several known messages.
- Send and receive a new message at the destination.
- Review skipped messages, quota errors, and size-limit errors.
Run Imapsync Again Before and After MX Cutover
Imapsync is designed for repeat runs and normally avoids duplicates using message identifiers. Run a bulk pass before changing DNS. At cutover, change MX, SPF, DKIM, DMARC, autodiscover, and client settings as required. Then repeat the same imapsync command to copy messages that arrived at the old server during DNS propagation.
Keep the source receiving mail until the old MX TTL has passed and delivery logs show the new route is stable. Run a final pass after the quiet period.
Migrate Multiple Mailboxes
For a batch, store account mappings in a permission-protected file and use an audited script that logs each exit code. Limit concurrency so providers do not throttle or block the migration IP. Never put plaintext passwords in a spreadsheet, shell script, shared ticket, or source-control repository.
- Start with two or three pilot users.
- Group mailboxes by size and complexity.
- Rate-limit transfers when the provider requires it.
- Retry only failed accounts.
- Record source count, destination count, exit code, and user acceptance.
Clean Up Credentials and Logs
rm /tmp/source-imap.pass /tmp/destination-imap.pass
Rotate temporary application passwords or revoke migration tokens. Protect logs because folder names and email addresses can be sensitive. Retain only what your audit and troubleshooting policy needs.
Common Problems
Authentication Failed
Confirm IMAP is enabled, use the complete username, check MFA/app-password or OAuth requirements, and test one login. Microsoft 365 and Gmail commonly require modern authentication.
Destination Quota Exceeded
Increase destination quota or reduce the planned source scope. Do not delete source data until the destination is verified and backed up.
Duplicate Messages
Keep the same imapsync options across repeat runs. Review identification headers, provider message rewriting, and the official duplicate FAQ before changing --useheader or UID options.
Folders Have Different Names
Test --automap with a pilot. For special folders, use explicit folder mapping documented by imapsync and the providers.
Frequently Asked Questions
Does imapsync delete source email?
Not by default. Destructive options exist, but they should not be used during a normal first migration.
Can I run imapsync more than once?
Yes. Repeat one-way runs are a core migration pattern, and already identified messages normally are not copied again.
Does imapsync move contacts and calendars?
No. IMAP covers mailboxes. Export or migrate contacts, calendars, rules, and other groupware data with provider-specific tools.
Conclusion
A safe imapsync migration uses encrypted IMAP, protected password/token files, a pilot mailbox, repeat passes, DNS planning, and message-level verification. Keep the source available until users approve the result and the rollback period ends.
If the destination is Zoho Mail, read our updated Zoho Mail migration guide before changing MX records.
Reviewed and updated: August 2026. Options and security behavior were checked against the official imapsync repository and manual and its security FAQ. Use the provider-specific OAuth documentation when password authentication is unavailable.
Comments