imapsync: Copying Mail Between IMAP Servers

When you move email to a new provider, you need to copy messages and folders from your old mailbox to your new one. imapsync is a command-line tool, a program you run from a text-based command line, that transfers mail between two IMAP servers. IMAP, or Internet Message Access Protocol, lets a mail program access messages and folders stored on a mail server. imapsync copies in one direction, from a source mailbox to a destination mailbox, and supports repeat runs that skip messages already transferred.

If you want a different kind of copy, mailmd is a free, open source alternative that saves email as Markdown files on your computer for local reading and searching. Choose imapsync when you want the destination to remain an IMAP mailbox. Choose mailmd when you want an archive of local files.

What imapsync copies #

imapsync transfers folders and messages between mailboxes. It also copies message flags, which record statuses such as read or starred, when the destination server allows them. imapsync runs on Windows, Linux, and macOS. It connects to servers over the internet or a local network, as described on the official imapsync site.

The transfer is incremental, meaning you can stop it and run it again later. imapsync skips messages it recognizes as already copied. By default, it compares the Message-Id and Received headers, fields in an email that store information about the message, to identify messages on both sides. If the servers alter those headers or you see duplicates, the imapsync manual documents --useheader for changing the headers used to identify matches.

imapsync handles email accessible through IMAP. It does not transfer contacts or calendars, which typically use other services or data formats. Its backup use is also limited to copying between IMAP accounts: it does not save or restore messages to a local directory. To copy mail between mailboxes, connect both accounts and set one as the source and the other as the destination.

Test the destination before transferring #

imapsync normally leaves the source mailbox unchanged, but it creates folders and messages and sets flags in the destination. The project’s Unix tutorial recommends testing with a dedicated destination account before changing a real user’s mailbox.

Start with --dry to check that imapsync can log in to both accounts and to see which destination folders it pairs with the source folders. The option does not transfer messages. After reviewing the folder pairings, run the transfer without --dry to copy the messages.

Folder names sometimes differ between providers. For example, a source folder named Sent Messages might need to map to a destination folder named Sent. The --f1f2 option lets you specify that mapping.

imapsync does not delete destination messages by default. Take care with the deletion options: --delete2 removes destination messages that are absent from the source, which can delete mail that arrived at the destination after you switched to using it. --delete1 removes source messages after successful transfer. Neither option is a routine cleanup step; use one only when its effect on both mailboxes is intended.

Check connections and migration results #

The imapsync online-service FAQ says its service tries to use SSL or TLS, protocols for encrypting a connection, when the server supports them. By default, the service does not check whether the server's certificate is genuine. If a server lacks SSL or TLS, credentials and messages can travel without encryption. Before transferring mail, check how each server connection is secured, especially if you use a hosted service.

Provider authentication requirements vary. Some IMAP providers require an app password, and Google or Microsoft accounts may have separate access requirements. Check the provider’s current instructions and confirm that the account permits IMAP access before starting.

The source and destination can show different total mailbox sizes even when the transfer succeeds. Servers can report message sizes differently, and Gmail does not count duplicate messages across folders twice. Check imapsync’s transfer results, then inspect some folders and messages. Matching size totals alone do not prove the transfer succeeded.

When mailmd is the better fit #

Choose mailmd when you want to keep email as files on your own computer rather than copy it into another IMAP mailbox. It saves each message as a Markdown file, with message details in a block at the start of the file. It converts HTML mail to readable Markdown and stores attachments beside the message. Folder and year directories organize the files, while index.jsonl lists messages for scripts. The --keep-raw option also saves the original .eml message.

mailmd reads mail without marking it as read, moving it, deleting it, or sending mail. It adds new mail on later syncs and updates read and starred marks. It never deletes archived files, including files for messages later deleted from the server. You can search the archive with an editor, rg, or grep, and filter its index with jq; mailmd does not include its own search engine.

For Gmail, mailmd connects through the Gmail API; for Outlook.com and Microsoft 365, it uses Microsoft Graph. These connections use OAuth, a way for an app to get permission to access an account, and require you to create an app in Google Cloud or Microsoft Entra. Other IMAP accounts connect through IMAP. Logins are stored outside the archive, unencrypted and readable only by your user account. If you use an AI coding agent to search the files, it sends the mail it reads to the provider that runs its AI model.

To try mailmd, follow the setup instructions on mailmd’s website or review its source code and project instructions. mailmd stores messages as files. It does not import them back into a mailbox or convert them to PST or PDF.

$ curl -fsSL https://raw.githubusercontent.com/vincentsch/mailmd/main/install.sh | sh

Set up mailmd so you can read my email. Use https://github.com/vincentsch/mailmd: read its AGENTS.md and follow the steps. Connect my mailbox and run the first sync. Then show me where the files are.