imapsync Parameters That Prevent Missing Mail (and the Mistakes That Break It)

 

imapsync is not a file copy utility. It is a state-aware synchronization engine that translates data between two live IMAP stores. It must negotiate divergent server dialects, handle network latency, and map incompatible folder structures in real-time.

If you run imapsync with default settings, you are not migrating; you are gambling. Defaults assume a perfect network and standards-compliant servers—conditions that rarely exist in the wild. A single missing parameter can cause silent data loss, massive duplication, or IP bans from providers like Google and Microsoft.

This guide details the specific parameters required to prevent data loss, the mechanics behind common failures, and the forensic verification steps needed before you cut DNS.

For a broader architectural view of the migration lifecycle, see imapsync: How to Use It for Email Migration (Safe Flags, Folders, and Verification).

---

1. Connection Stability & State Preservation

The Failure Mode: Partial Transfers & Timeouts

Most "missing mail" reports are actually "failed transfer" reports. Large attachments (25MB+) and slow legacy servers (Exchange 2010/2013) often trigger timeouts before the APPEND command completes. If the connection drops, the message is skipped.

The Fix: Aggressive Keepalives

You must override the default timeouts to account for "Whale" mailboxes and aggressive firewalls that cut idle TCP connections.

--timeout 120 --keepalive1 --keepalive2

 

• --timeout 120: Increases the network timeout to 120 seconds. This is mandatory for mailboxes containing large PDF or CAD attachments.
• --keepalive1 / --keepalive2: Sends TCP keepalive packets to both Source (1) and Destination (2). This prevents stateful firewalls or load balancers from severing the connection during long pauses (e.g., while the tool is calculating a checksum).

The Fix: Local State Caching

Migration is rarely a single-pass event. You will run a bulk pass, hit errors, fix them, and resume. Without caching, imapsync must re-fetch the file list from both servers (expensive UID FETCH operations) every time.

--usecache

 

• Mechanism: Saves the migration state (UIDs mapped to Message-IDs) in a local database.
• Benefit: Reduces resume time from hours to minutes. It ensures the tool only attempts to move items that have not yet been successfully transferred.

---

2. The "Missing Folder" Illusion (Mapping & Encoding)

The Failure Mode: Hierarchy Flattening & UTF-7 Errors

Users often claim folders are "gone" when they have actually been flattened or misnamed due to namespace collisions.

The Delimiter Trap (Dot vs. Slash)

IMAP servers use different characters to separate folder levels.

• Dovecot/Courier: Uses . (e.g., INBOX.Clients.ProjectA)
• Exchange/Office 365: Uses / (e.g., INBOX/Clients/ProjectA)

If you migrate from Dovecot to Exchange without mapping, imapsync may interpret INBOX.Clients.ProjectA as a filename, creating a single root-level folder with dots in the name, destroying the nested structure.

The Parameter:

--regextrans2 's/\./\//g'

 

• Logic: "On Destination (2), substitute every dot (.) with a slash (/) globally."

The "Sent" Folder Schism

Every provider names the Sent folder differently. If unmapped, users see their old sent mail in a new archive folder rather than their active "Sent Items."

Source Provider	Raw Folder Name	Target (Standard)	Parameter
Gmail	[Gmail]/Sent Mail	Sent Items	--regextrans2 's/^\[Gmail\]\/Sent Mail/Sent Items/'
German Hosts	Gesendete Elemente	Sent Items	--regextrans2 's/^Gesendete Elemente/Sent Items/'
Generic/cPanel	Sent	Sent Items	--regextrans2 's/^Sent/Sent Items/'

UTF-7 Encoding Nightmares

IMAP uses a modified UTF-7 encoding for non-ASCII characters. If you see folder names like &BB8EQAQ+BDUEOgRC-, the encoding translation failed.

• The Fix: Use --automap to attempt automatic common folder mapping, or use --regextrans2 to explicitly rename known localized folders to English equivalents if the destination does not support the source encoding.

---

3. Throttling & API Limits (The "Invisible Wall")

The Failure Mode: HTTP 429 & IP Bans

Migration looks like a Denial of Service (DoS) attack to the receiving server. Google and Microsoft enforce strict rate limits. If you exceed them, you trigger "Back Pressure" (HTTP 429) or a temporary lockout (Google 24h suspension).

Google Workspace Limits

• Download Cap: ~2,500 MB per day per account.
• Upload Cap: ~500 MB per day per account.
• Consequence: If you try to move a 10GB mailbox in one hour, Google will cut the connection.

Microsoft 365 Limits

• Concurrency: Max ~20 connections per user.
• Throttling: Dynamic based on tenant health.

The Parameters:

--maxbytespersecond 500000 --maxmessagespersecond 2

 

• --maxbytespersecond 500000: Caps transfer speed at 500KB/s. This keeps you under the radar of most automated abuse detection systems.
• --maxmessagespersecond 2: Prevents "bursting" small messages, which consumes high IOPS and triggers rate limiting on shared hosts.

Note for Agencies: When migrating to TrekMail, our infrastructure is designed for high-concurrency ingestion. You can typically run without these throttles, significantly reducing migration time compared to M365.

---

4. Authentication: The Modern Auth Cliff

The Failure Mode: "Authentication Failed" despite correct password

As of 2025, Basic Authentication (user/pass) is deprecated or disabled by default on Google Workspace and Microsoft 365. Legacy imapsync scripts using plain passwords will fail with generic login errors (e.g., Google 11001).

The Fix: OAuth2 Tokens

You cannot use the user's login password. You must use an OAuth2 Access Token.

--authmech1 XOAUTH2 --oauthaccesstoken1 "ya29.a0..."

 

• Requirement: You must register an application in the source tenant (Google Cloud Console or Azure AD), grant it Mail.Read (or FullAccess), and generate a token.
• Alternative (SMBs): If OAuth is too complex for a single domain, enable 2FA on the source account and generate an App Password. Use this 16-character string in place of the user's password.

---

5. Data Integrity: Handling "Bad" Items

The Failure Mode: Silent Skips & Corrupt Headers

Legacy servers often contain "poison" items—messages with corrupt MIME headers, zero-byte bodies, or massive attachments that violate destination limits.

The "Whale" Filter

Attempting to move a 100MB attachment to a server with a 50MB limit will cause a fatal error for that message.

--maxsize 35000000

 

• Strategy: Skip items >35MB in the main pass. Log them, and handle them manually (e.g., download and send via file transfer) rather than letting them stall the batch.

The "Ghost" Message Fix

Some messages lack a Message-ID header entirely. imapsync relies on this header for deduplication.

--addheader

 

• Function: Injects a generated Message-ID into the header of messages that lack one. This allows the message to be transferred and tracked, preventing it from being skipped as "invalid."

---

6. The "Zombie" Data Risk (--delete2)

The Failure Mode: Accidental Deletion of New Mail

The --delete2 parameter is a powerful tool for mirroring deletions, but it is the primary cause of data loss during the cutover window.

--delete2

 

• Logic: "If a message exists on Destination but NOT on Source, DELETE it from Destination."
• The Danger Zone:
1. You switch MX records to the new server.
2. New mail arrives at the new server (Destination).
3. You run imapsync with --delete2 to catch up on old emails.
4. The tool sees the new email on the Destination, notes that it does not exist on the old Source, and deletes it.

The Rule: NEVER use --delete2 after the MX record has been changed. Only use it during the pre-stage phase to clean up items deleted by the user before the switch.

---

7. Forensic Verification: When UIDs Fail

The Failure Mode: Massive Duplication

IMAP servers use UIDVALIDITY to track folder states. If a source folder is corrupted and rebuilt (common on older Exchange or cPanel servers), the UIDVALIDITY changes. imapsync will assume it is a brand new folder and re-download everything, creating duplicates of every message.

The Fix: Header-Based Deduplication

If you suspect the source server is unstable, do not trust the UIDs.

--useheader "Message-Id"

 

• Trade-off: This is significantly slower because the tool must read the headers of every message on both sides.
• Benefit: It guarantees zero duplicates, even if the server index is completely broken. Use this for the final "safety check" pass.

---

Summary: The Operator's Checklist

For a safe migration, your command line should resemble this structure:

imapsync \

  --host1 imap.gmail.com --user1 user@source.com --passfile1 ./pass1 \

  --host2 imap.trekmail.net --user2 user@dest.com --passfile2 ./pass2 \

  --timeout 120 --keepalive1 --keepalive2 \

  --usecache \

  --regextrans2 's/^\[Gmail\]\/Sent Mail/Sent Items/' \

  --exclude "^\[Gmail\]/All Mail" \

  --maxbytespersecond 500000 \

  --dry

 

1. Verify Connectivity: --timeout 120, --keepalive
2. Map Structure: --regextrans2
3. Protect Quotas: --exclude "All Mail", --maxbytespersecond
4. Test First: --dry

The "Easy Button" for Agencies

Understanding these parameters is mandatory if you are manually scripting migrations. However, managing regex maps, OAuth tokens, and throttling limits for 50+ domains is a poor use of engineering time.

TrekMail was built to eliminate this friction.

• Automated Intelligence: Our built-in migration tool automatically applies the correct regex mappings for Gmail, cPanel, and Exchange.
• High-Speed Ingestion: We optimize the receiving side to accept high-concurrency streams, reducing the need for aggressive throttling.
• Flat-Rate Economics: You stop paying per-user fees to Google/Microsoft, and you stop burning hours on migration scripts.

Stop fighting DNS. Try TrekMail for free.