IMAPSync

imapsync, also commonly written as IMAPSync, is a tool for copying and migrating email messages between two mailboxes that support the IMAP protocol. It is commonly used to move email from an old server to a new one while preserving the folder structure and most message-related information.

Organizations frequently use imapsync when changing email providers, moving mailboxes to new hosting, transferring company email to a different service, or creating a copy of a mailbox on another IMAP server.

The tool operates in one direction. It reads the source mailbox, identified as host1, and copies its contents to the destination mailbox, known as host2. By default, it does not delete messages from the source account.

How does imapsync work?

Imapsync connects to two mailboxes at the same time:

• host1 – the source server and mailbox from which messages are retrieved;
• host2 – the destination server and mailbox to which the messages are copied.

A connection usually requires:

• the source and destination IMAP server addresses;
• a username for each mailbox;
• a password, app password, or authentication token;
• the appropriate port number;
• the required connection-encryption method.

Port 993 is the standard port for IMAP secured with SSL/TLS. Port 143 is generally used for an unencrypted connection or one upgraded through STARTTLS. The exact configuration depends on the email provider.

After connecting, imapsync reads the folders and messages available in the source mailbox. It then creates the corresponding folders on the destination server and copies messages into them. On subsequent runs, it compares the two mailboxes and primarily transfers items that are still missing.

What can imapsync transfer?

The exact results depend on the capabilities of both IMAP servers. Imapsync can transfer:

• messages in the inbox;
• sent messages;
• drafts;
• messages stored in the trash;
• user-created folders;
• subfolders and their hierarchy;
• attachments contained within messages;
• message dates and IMAP internal dates;
• common flags such as read, unread, flagged, and deleted.

Attachments are not copied as separate files. They are part of the email message and therefore move together with it.

Some mailbox properties may be represented differently by individual providers. For example, one server may use a folder called Sent, another may use Sent Items, and a localized service may use a translated name. Folder mapping may be required when the source and destination use different conventions.

What does imapsync not transfer?

Imapsync works through the IMAP protocol and therefore does not perform a complete migration of the entire user account. It cannot transfer information that is not exposed through IMAP.

The tool does not automatically migrate:

• contacts and address books;
• calendars and events;
• tasks and notes;
• email rules and filters;
• email signatures;
• automatic replies;
• forwarding settings;
• email aliases;
• user passwords;
• anti-spam settings;
• administrative permissions;
• email-client configuration;
• DNS records used to route and authenticate email.

Contacts can often be exported to CSV or vCard files, while calendars can typically be exported in ICS format. The correct migration procedure depends on the source and destination services.

Imapsync also does not modify the MX, SPF, DKIM, or DMARC records associated with a domain. DNS configuration is a separate stage of an email migration.

Incremental email migration

One of imapsync’s most important features is incremental migration. A transfer can be interrupted and restarted without copying the entire mailbox again from the beginning.

On a later run, the tool compares the mailboxes and skips messages that have already been transferred. This makes it possible to:

• perform an initial migration of a large mailbox;
• resume a transfer after a connection failure;
• copy messages received after the first migration;
• run a final synchronization immediately before changing email servers;
• repeat the transfer after switching the MX records.

The process is designed to avoid duplicates, although its effectiveness also depends on message structure and server behavior. Incorrect folder mapping or unsuitable command options may still create additional copies.

Does imapsync provide two-way synchronization?

No. Imapsync is intended primarily for one-way copying from host1 to host2. It is not suitable for continuously synchronizing two active mailboxes when users independently delete, move, and modify messages on both sides.

During a migration, the direction should remain clear:

1. the old mailbox is the source;
2. the new mailbox is the destination;
3. subsequent runs add missing messages to the new account.

Reversing the host parameters may copy messages in the opposite direction. Before starting the migration, the operator should confirm which server has been assigned as host1 and which is host2.

Example imapsync command

A basic command for Linux or macOS may look like this:

imapsync \
  --host1 imap.old-server.example \
  --user1 office@example.com \
  --passfile1 /secure/path/source.pass \
  --ssl1 \
  --host2 imap.new-server.example \
  --user2 office@example.com \
  --passfile2 /secure/path/destination.pass \
  --ssl2

The parameters specify:

• --host1 – the source IMAP server;
• --user1 – the source mailbox username;
• --passfile1 – a file containing the source password;
• --host2 – the destination IMAP server;
• --user2 – the destination mailbox username;
• --passfile2 – a file containing the destination password;
• --ssl1 and --ssl2 – encrypted IMAP connections.

A password can be supplied directly as a command-line argument, but it may then appear in the shell history or the operating system’s process list. Password files, environment variables, or interactive password entry are safer alternatives.

The --dry option can be used before the actual migration. It helps test parts of the configuration and displays planned operations without performing a standard message transfer.

Using imapsync when changing email hosting

Copying messages is only one part of a company email migration. A typical provider change should include:

1. creating the mailboxes on the new server;
2. confirming the correct IMAP settings for both services;
3. checking mailbox storage quotas;
4. testing the migration with one account;
5. performing the initial message transfer;
6. checking folders, dates, attachments, and message counts;
7. configuring MX, SPF, DKIM, and DMARC records;
8. switching mail delivery to the new server;
9. performing a final incremental transfer;
10. keeping the old server available for an agreed safety period.

The initial transfer can take place before the MX records are changed. Users may continue receiving email on the old server during this period. Imapsync should then be run again near or after the cutover to copy messages that arrived after the first transfer.

Authentication methods

Not every provider allows users to connect to IMAP with their regular account password. The required authentication method may depend on the provider’s security policy and the mailbox configuration.

Possible methods include:

• a standard username and password;
• a dedicated app password;
• OAuth 2.0 authentication;
• an administrative account authorized to access user mailboxes;
• provider-specific authentication mechanisms.

Services such as Google Workspace and Microsoft 365 may require additional configuration, enabled IMAP access, a registered application, or an OAuth 2.0 token. A password that works in the provider’s web interface is not always sufficient for an IMAP connection.

Why can’t imapsync connect to a server?

A connection error involving host1 or host2 can have several causes. The operator should check:

• whether the IMAP server address is correct;
• whether the full email address is required as the username;
• whether the password is correct;
• whether an app password is required;
• whether IMAP access has been enabled;
• whether the port matches the selected encryption method;
• whether the server supports SSL/TLS on port 993;
• whether STARTTLS is required on port 143;
• whether the provider has disabled basic authentication;
• whether repeated attempts have temporarily locked the account;
• whether a firewall is blocking the outbound connection;
• whether access is restricted by IP address;
• whether the destination mailbox has already been created;
• whether the destination account has sufficient free storage.

An “authentication failed” message usually indicates an incorrect username, password, or authentication method. “Connection refused” may indicate the wrong server, port, or a network restriction. A timeout may result from a firewall, unavailable server, or overloaded email service.

Folder-mapping problems

IMAP servers may use different folder names, prefixes, and hierarchy separators. One server may store a folder as INBOX/Projects, while another expects INBOX.Projects.

A migration may produce:

• duplicate sent-mail folders;
• an unwanted INBOX prefix;
• separate Sent and Sent Items folders;
• problems with localized folder names;
• folders that the destination server refuses to create;
• different representations of trash, archives, or spam;
• duplicate messages created from labels.

Imapsync provides options for selecting, excluding, and renaming folders. These rules should be tested with one mailbox before they are applied to a large migration.

Imapsync and Gmail labels

Gmail exposes many of its labels as IMAP folders. A single message can have several labels even though Gmail stores it as one item. When the mailbox is migrated to a conventional IMAP server, the message may be stored as a separate copy in each corresponding folder.

Before migrating from Gmail, it is important to determine:

• which labels should be transferred;
• whether the “All Mail” folder should be included;
• how sent messages, spam, and trash should be mapped;
• whether IMAP access is enabled;
• whether OAuth 2.0 or an app password is required;
• whether the provider imposes connection and transfer limits.

Can imapsync be used as an email backup?

Imapsync can copy messages to another IMAP mailbox, so it may form part of an archiving process. However, it does not create a conventional local backup directory or a standalone backup file.

A second mailbox should not automatically be treated as a complete backup. If the synchronization uses options that delete data from the destination, accidental deletions may also affect the copy. A professional backup system should provide versioning, retention policies, access controls, and point-in-time recovery.

Is imapsync secure?

Security depends primarily on how the tool is operated and how credentials are protected. Imapsync requires access to both mailboxes, which means the person performing the migration may potentially access all transferred correspondence.

A secure migration should:

• use encrypted SSL/TLS connections;
• avoid sending passwords through ordinary email;
• avoid storing credentials in public scripts;
• restrict access to password files;
• protect migration logs;
• use app passwords or tokens when available;
• revoke temporary credentials after the migration;
• delete local password files when they are no longer required;
• verify the destination before deleting the old mailbox.

When the online version of imapsync is used, mailbox credentials are provided to an external service. Organizations should review its security and privacy terms before transferring sensitive correspondence. Running imapsync within a controlled environment may be preferable for confidential business email.

Migrating multiple mailboxes

Imapsync can transfer a single account or a large collection of mailboxes. For a multi-user migration, commands can be automated using a prepared list of accounts.

This process requires additional planning, including:

• creating an inventory of addresses and aliases;
• measuring the size of each mailbox;
• creating all destination accounts;
• obtaining credentials securely;
• respecting the provider’s connection limits;
• creating separate logs for individual accounts;
• detecting errors and retrying failed transfers;
• comparing folder and message counts;
• notifying users about the cutover schedule;
• providing new email-client settings.

A successful test with one mailbox does not guarantee an identical result for every account. Individual users may have different folders, unusually large messages, incompatible names, exceeded quotas, or damaged items.

Common imapsync mistakes

Common mistakes include:

• reversing the source and destination servers;
• entering an SMTP or webmail address instead of an IMAP server;
• using a port that does not match the encryption method;
• providing a regular password when an app password or OAuth 2.0 is required;
• failing to test a single mailbox first;
• not checking the destination storage quota;
• incorrectly mapping folders;
• overlooking the way Gmail labels work;
• using deletion options without a dry run;
• canceling the old email service immediately after the first transfer;
• failing to run a final incremental migration;
• assuming contacts, calendars, and account settings were also transferred;
• leaving passwords in shell history or unsecured files;
• failing to review logs and error summaries.

Summary

Imapsync is designed for one-way copying between two IMAP accounts. It simplifies changes between email providers by supporting incremental transfers, preserving folder hierarchies, and allowing interrupted migrations to resume without starting again from the beginning.

It does not provide a complete migration of the entire email environment. Contacts, calendars, rules, aliases, DNS configuration, and user settings must be handled separately. A reliable migration also requires credential testing, folder-mapping checks, log review, and a final synchronization after mail delivery has been switched to the new server.