imapsync Tool: Flags That Prevent Missing Mail

imapsync is the tool people reach for when they need to move IMAP mail without dragging users through PST exports, desktop clients, or a weekend of guesswork. That part is fine. The problem is what happens next. One bad flag, one bad folder map, one bad assumption about auth, and your migration finishes with missing Sent mail, duplicate folders, or new mail deleted at cutover. If you need the wider workflow first, read this operator guide to imapsync.

That’s why this article is narrow on purpose. It covers the imapsync parameters that actually change outcomes: timeouts, keepalives, folder mapping, throttling, dedupe, and the deletion flags that can wreck a live mailbox. If you’re moving a single account, this saves you from a messy rerun. If you’re moving fifty, it saves you from explaining to clients why their Sent folder split into three copies.

The short version: default imapsync settings are not a migration plan. They’re a starting point. Real migrations need staged passes, explicit folder rules, and verification before you touch MX. If the destination is TrekMail, the built-in import wizard on paid plans can handle the receiving side inside the dashboard, which is faster than hand-managing every mailbox with shell scripts. TrekMail’s platform starts at $3.50/month, uses pooled storage instead of per-user billing, and supports server-side IMAP import for Gmail, Outlook, Yahoo, iCloud, and generic IMAP.

Why imapsync Breaks When Operators Trust Defaults

imapsync copies mail between live IMAP stores, not flat files. It has to deal with different folder hierarchies, server quirks, message identifiers, and authentication models while the network is trying to interrupt the session. That’s why safe imapsync runs always look more explicit than the examples people paste into forums.

The common failures are boring and expensive:

1. Large messages time out during upload.
2. Folder names map badly, so users think mail vanished.
3. Providers throttle the job and start refusing connections.
4. Modern auth blocks plain passwords.
5. UID state changes trigger duplicates on later passes.
6. `--delete2` wipes fresh mail from the target after cutover.

If you’ve ever had a migration that was “mostly fine except for Sent Items,” that wasn’t random. It was predictable. The protocol gave you enough rope, and the defaults didn’t save you.

Connection Flags That Keep imapsync Alive

For large mailboxes, imapsync usually fails because the connection dies before the message write finishes. Long APPEND operations, slow Exchange boxes, and stateful firewalls are the usual culprits. The fix is simple: increase timeout tolerance, send keepalives, and cache state so reruns don’t start from scratch.

Use these flags on the first serious pass:

imapsync \
  --host1 imap.source.tld --user1 user@source.tld --passfile1 ./pass1 \
  --host2 imap.dest.tld   --user2 user@dest.tld   --passfile2 ./pass2 \
  --timeout 120 \
  --keepalive1 --keepalive2 \
  --usecache

What each one does:

The cache point matters more than most people think. Good migrations are incremental. You run a bulk pass, fix auth or mapping issues, then run one or two catch-up passes. With `--usecache`, imapsync spends less time re-reading both sides. Without it, every rerun is heavier than it needs to be.

There is one catch. The official imapsync docs warn that `--usecache` is not safe with size- and age-filtering combinations in some cases. Don’t pile on random filters just because they sound efficient. Keep the first pass boring.

Folder Mapping Flags That Stop the “Missing Folder” Panic

When users say imapsync lost folders, the mail is often still there. The real issue is that the destination interpreted the source folder path differently, or a localized special-use folder never got mapped to the user’s active Sent folder. imapsync needs explicit translation when providers disagree.

The two big traps are hierarchy delimiters and special folders.

Example: some servers use dots for nesting, others use slashes. If the source has INBOX.Clients.ProjectA and the destination expects INBOX/Clients/ProjectA, you need to rewrite the folder path during the copy.

imapsync \
  --host1 old.example.com --user1 user@old.example.com --passfile1 ./pass1 \
  --host2 imap.trekmail.net --user2 user@example.com --passfile2 ./pass2 \
  --regextrans2 's/\./\//g'

Now the Sent folder problem. Providers call it different things, and users only care whether their mail shows up in the active Sent view.

If the mailbox has standard special folders, try --automap first. If you’re migrating messy, localized, or years-old cPanel mailboxes, explicit regex transforms are safer. TrekMail also has source-specific guides for starting an import in the dashboard and for domain prep in adding a domain, which matters if you’re staging the destination before cutover.

Conceptual example: the folder didn’t disappear. It moved from the user’s expected Sent folder into a raw archive-style folder name the client doesn’t treat as “Sent.” Same bytes. Wrong place. Same support ticket anyway.

Throttle imapsync Before Google or Microsoft Throttles You

imapsync can look like abusive traffic to hosted mail providers. Fast bursts of APPEND and FETCH commands across many mailboxes trigger rate controls, temporary suspensions, or failed auth-looking errors that are really capacity controls. Slow and steady is often faster than getting blocked.

If you’re hitting Google Workspace or Microsoft 365, control the pace:

imapsync \
  --host1 imap.gmail.com --user1 user@source.tld --passfile1 ./pass1 \
  --host2 imap.trekmail.net --user2 user@dest.tld --passfile2 ./pass2 \
  --maxbytespersecond 500000 \
  --maxmessagespersecond 2

This does two things. First, it reduces throughput spikes that trigger provider defenses. Second, it keeps shared environments from getting hammered by tiny-message bursts. That matters on old cPanel boxes and on Office 365 tenants that already have enough going on.

Don’t treat the numbers as sacred. They’re starting values. The right limit depends on mailbox size, concurrency, and how much anger the source provider has for long-running IMAP jobs. The operational rule is simple: if a migration starts fine and then degrades into intermittent failures, slow it down before you assume the password is wrong.

This is also where “old way vs new way” becomes obvious.

Old way: hand-script every mailbox, tune throttles by trial and error, and babysit failures at 2 a.m.

New way: use TrekMail’s built-in server-side import on paid plans for the receiving side, keep your destination standardized, and avoid per-user pricing while you do it. Agencies juggling many domains usually care less about one mailbox finishing ten minutes sooner and more about not spending three days triaging retries. If that’s your world, read this guide to multi domain email hosting.

Authentication Flags for 2025-2026: Passwords Fail, OAuth Wins

For Google Workspace and Microsoft 365, plain username-and-password IMAP auth is no longer something you can assume will work. Google states that, starting May 1, 2025, Workspace accounts no longer support “less secure apps” that sign in with just username and password. Microsoft’s Exchange Online guidance points IMAP clients to OAuth as well.

That changes how you run imapsync. If the source supports XOAUTH2, you need an access token instead of the user’s normal password.

imapsync \
  --host1 outlook.office365.com \
  --user1 user@source.tld \
  --authmech1 XOAUTH2 \
  --oauthaccesstoken1 "ACCESS_TOKEN" \
  --host2 imap.trekmail.net \
  --user2 user@dest.tld --passfile2 ./pass2

On Google Workspace, app passwords can still be a practical fallback for one-off mailbox moves when 2-Step Verification is enabled. On Microsoft 365, use the OAuth flow Microsoft documents for legacy protocols. If your script still assumes “correct password means correct auth,” you’re behind the current reality.

Authority links: Google’s Workspace guidance on less secure apps and Microsoft’s OAuth instructions for IMAP.

Integrity Flags That Keep imapsync From Skipping Bad Mail

Some messages are broken. That’s normal on old servers. Missing Message-ID headers, malformed MIME, giant attachments, and zero-byte bodies all show up in real migrations. imapsync can work around some of this, but only if you tell it how.

The first useful flag is --addheader. The official imapsync docs say it adds a generated Message-Id header when a message lacks one. That matters because message identity is how imapsync decides what already exists.

The second is --maxsize. If the destination mailbox or policy rejects giant messages, don’t let one whale stall the whole job.

imapsync \
  --host1 old.example.com --user1 user@old.example.com --passfile1 ./pass1 \
  --host2 imap.trekmail.net --user2 user@example.com --passfile2 ./pass2 \
  --addheader \
  --maxsize 35000000

This is not about pretending those large messages don’t exist. It’s about moving the 99% first, then handling the outliers manually with a controlled exception list.

If you’re doing many mailbox rollouts in parallel, pair this with a clean provisioning process. TrekMail’s bulk create email accounts guide is worth reading because migration problems get worse when mailbox creation, password delivery, and DNS changes are all happening from different spreadsheets.

The imapsync Flag That Causes the Worst Data Loss: --delete2

`--delete2` tells imapsync to remove messages from the destination that do not exist on the source. That sounds useful for exact mirroring. It is also the easiest way to delete perfectly valid new mail after MX cutover if you run it at the wrong time.

Here’s the failure sequence:

1. You pre-stage old mail from source to destination.
2. You switch MX to the new provider.
3. Fresh mail starts landing on the destination.
4. You rerun imapsync with --delete2.
5. imapsync sees target-only mail and deletes it because it never existed on the source.

That is not a bug. That is exactly what you told it to do.

Use `--delete2` only in a controlled pre-cutover mirror scenario when both sides are still logically tied to the old source of truth. Once MX changes, keep it out of the command. If you need the destination live and receiving, treat it as authoritative for new mail.

When UIDs Lie, Use Header-Based Matching in imapsync

IMAP UIDs are only reliable inside the server state they belong to. RFC 3501 defines UIDVALIDITY precisely because UID assumptions can break when mailbox state changes. If a source folder is rebuilt or reindexed, imapsync may think every message is new and duplicate the lot on a later pass.

That’s when header-based matching helps:

imapsync \
  --host1 old.example.com --user1 user@old.example.com --passfile1 ./pass1 \
  --host2 imap.trekmail.net --user2 user@example.com --passfile2 ./pass2 \
  --useheader 'Message-Id'

This is slower than trusting server UIDs. It is also safer when the source is unstable, rebuilt, or obviously inconsistent. The official imapsync docs note that duplicate problems are often solved by switching to --useheader "Message-Id".

For final verification, I prefer a dry pass with conservative matching before DNS cutover, then a short delta pass after users stop writing to the old system.

A Safe imapsync Command Template

A safe imapsync run is explicit about connectivity, mapping, exclusions, and test mode. Start dry, confirm folder behavior, then run the real pass. Don’t touch production mail with a first draft command.

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 \
  --automap \
  --regextrans2 's/^\[Gmail\]\/Sent Mail/Sent Items/' \
  --exclude '^\[Gmail\]/All Mail' \
  --maxbytespersecond 500000 \
  --maxmessagespersecond 2 \
  --dry

Three practical notes:

1. Use --dry first. Always.
2. Exclude giant archive folders you don’t need in the first pass.
3. Record the log and keep your command lines versioned per migration batch.

Once the mailbox lands on TrekMail, users connect over standard IMAP at imap.trekmail.net on port 993. TrekMail is IMAP-only, not POP3, which is the right trade if you want synced state across devices instead of inbox roulette.

Conclusion: imapsync Works Fine When You Operate It Like a Migration Tool

imapsync is still the right tool for a lot of email moves. But only if you treat it like stateful migration software instead of a dumb copy command. Set timeouts. Use keepalives. Map folders deliberately. Slow down when providers push back. Use modern auth. Keep `--delete2` away from post-cutover mail. And when UID state looks dirty, force header-based matching.

If you want the receiving side easier to manage, TrekMail gives you a multi-domain destination with flat-rate pricing, pooled storage, built-in server-side import on paid plans, and no per-user tax every time you add another mailbox. For the operational baseline after the move, this article on business email is a good next read.