From Inbox to Inbox: A Deep Dive into imapsync’s Fun Features and Best Practices

Email migration is a perennial pain point for enterprises, especially when the source and target systems differ in protocol, security, or folder structure. Open‑source tooling has stepped in to fill the gap, with imapsync standing out for its flexibility, speed, and low footprint. The FAQ’s Fun Things section (source: https://imapsync.lamiral.info/FAQ.d/FAQ.Fun_Things.txt) distills many of the tool’s hidden gems—options that can turn a tedious, error‑prone task into a streamlined, auditable process.

1. The Core Sync Command

At its heart, imapsync is a single‑line command. A typical invocation looks like this:

imapsync \
  --host1 imap.source.com \
  --user1 [email protected] \
  --password1 'sourcepass' \
  --host2 imap.target.com \
  --user2 [email protected] \
  --password2 'targetpass' \
  --delete2 \
  --syncinternaldates
  • --delete2 removes messages from the target that no longer exist on the source, keeping the two mailboxes in lockstep.
  • --syncinternaldates preserves the original timestamps—critical for compliance audits.

The FAQ’s Fun Things add layers of nuance to this basic pattern.

2. Leveraging Advanced Options

a. Skipping Large Attachments

Migrating a mailbox full of marketing PDFs can be a bandwidth nightmare. Use --maxsize to skip files that exceed a threshold:

imapsync \
  ... \
  --maxsize 10M   # skip attachments larger than 10 megabytes

The tool logs the skipped messages, so you can review them later.

b. Parallelism for Speed

By default, imapsync processes one folder at a time. The --threads option spawns worker threads, dramatically reducing runtime on servers with high concurrency support:

imapsync \
  ... \
  --threads 4

This is especially useful when syncing thousands of accounts in a migration wave.

c. Handling Folder Name Discrepancies

Many providers use different naming conventions (e.g., Gmail’s \Inbox vs. Exchange’s INBOX). The --folderfilter and --foldermap options let you map or exclude folders on the fly:

imapsync \
  ... \
  --folderfilter '^INBOX' \
  --foldermap 'INBOX:Inbox'

The FAQ notes that regular expressions are powerful but should be tested in a sandbox first.

3. Testing Before You Commit

A recurring theme in the FAQ is the importance of a dry‑run. The --dry flag performs a full sync without writing any data:

imapsync \
  ... \
  --dry

Use the output to verify:

  • Folder counts match.
  • No messages are flagged as DELETED on the target.
  • The --syncinternaldates flag correctly preserves timestamps.

After a successful dry‑run, drop the flag and run the real sync.

4. Common Pitfalls and How to Avoid Them

Pitfall Symptom Fix
SSL/TLS Mismatch Connection errors or TLS handshake failed Use --ssl1, --ssl2, or --tls1 to force the desired protocol.
Quota Overrun Target mailbox stops accepting messages mid‑sync Pre‑create the target mailbox with sufficient quota or use --maxsize to throttle.
Duplicate Messages Same message appears twice Ensure --delete2 is set and that both servers support UIDVALIDITY.
Time‑Zone Drift Timestamps shifted by hours Use --syncinternaldates and verify the server’s clock is NTP‑synchronized.

The FAQ’s “fun” section also reminds users that imapsync can be scripted in CI pipelines, enabling automated post‑migration verification.

5. A Quick Checklist for Your Next Migration

  1. Audit Source and Target – Confirm IMAP capabilities, SSL support, and quota limits.
  2. Run a Dry‑Run – Verify folder mapping and message counts.
  3. Enable Parallelism – Use --threads if bandwidth allows.
  4. Set --delete2 and --syncinternaldates – Keep mailboxes aligned and audit‑ready.
  5. Log and Review – Examine the log file for skipped messages or errors.
  6. Rollback Plan – Keep a snapshot of the target before the sync in case of rollback.

By treating imapsync not just as a command but as a configurable pipeline, developers and migration teams can reduce downtime, avoid data loss, and meet compliance requirements with confidence.

Source attribution: https://imapsync.lamiral.info/FAQ.d/FAQ.Fun_Things.txt