What Most Email Clients Get Wrong About IMAP

In one internal compatibility pass, we hit provider-specific IMAP behavior differences in almost every major stack we tested. IMAP is universal, but implementations are not uniform.

IMAP is forty years old. The core protocol was first defined in 1986 and has been extended, revised, and adapted dozens of times since. The current standard, RFC 3501, was published in 2003. The protocol works — billions of email clients use it every day — but working and being easy to implement correctly are different things.

Most modern email client startups avoid raw IMAP. They use provider APIs instead. The Gmail API, the Microsoft Graph API, the iCloud Mail push extension. These APIs are easier to work with because they abstract the protocol complexity. They also introduce hard dependencies on specific providers and their specific business decisions.

Why teams avoid raw IMAP

Stateful sessions, extension variance, and brittle edge cases make IMAP expensive to implement correctly. API layers from large providers look easier because they abstract the hard parts.

IMAP is a stateful protocol. Unlike HTTP, where every request is independent, an IMAP session maintains connection state. The client selects a mailbox, executes commands against it, and receives asynchronous notifications when the server has updates. Managing this connection across network interruptions, reconnections, and multi-folder operations requires careful state machine design.

The protocol also has dozens of optional extensions. IDLE for push notifications. CONDSTORE for efficient sync. QRESYNC for resuming sync after a reconnect. Not all providers support all extensions. A client that assumes IDLE is available will break on servers that don't support it. A client that doesn't use CONDSTORE will over-fetch on every sync.

The hidden cost of API-first email clients

• Provider lock-in: support quality clusters around a few large ecosystems.
• Inconsistent behavior for non-primary providers.
• More server dependency to maintain feature parity.

The Gmail API covers Gmail. The Microsoft Graph API covers Outlook. Neither covers iCloud, Fastmail, Protonmail, or any of the thousands of custom domain IMAP providers. If you build on top of these APIs, you are building a Gmail client and an Outlook client, not an email client.

Beyond coverage, API-first clients introduce a dependency on provider decisions. The Gmail API has changed multiple times. Access scopes have been tightened, requiring expensive security audits for new applications. Features have been added and removed. A client built on the Gmail API is subject to Google's roadmap, Google's pricing, and Google's approval process.

Where provider implementations diverge

In our compatibility testing, we found meaningful behavioral differences across providers in the following areas:

• SEARCH behavior: how body search is executed, what fields are indexed, how quickly results reflect new messages
• IDLE support: whether push notifications are available, timeout behavior, reconnect handling
• Flag semantics: how \Seen, \Answered, and custom flags are handled and propagated
• Folder naming: the hierarchy separator character, the INBOX special-case, the relationship between server-side labels and folders
• UID stability: whether message UIDs persist across reconnects and folder operations

Handling all of this correctly requires building an explicit compatibility layer — a per-provider configuration that documents known deviations and applies behavioral overrides at the protocol layer. It is not glamorous engineering, but it is the work that separates a client that works for most people on Gmail from a client that works for everyone on everything.

What robust IMAP support actually requires

1. Provider compatibility layer with explicit behavioral overrides.
2. Graceful fallback strategy for extensions and sync states.
3. Idempotent sync model for failure and reconnection scenarios.
4. Local indexing strategy that does not depend on remote search quality.

The fourth point is worth emphasizing. Remote IMAP SEARCH is unreliable for the reasons described in Why Apple Mail Search Feels Bad. A client that depends on it for search quality will deliver inconsistent results. The correct solution is local indexing — downloading messages and maintaining a local full-text index that is queried instead of, or in addition to, the server.

The sync correctness problem

IMAP sync is not just about fetching new messages. It is about maintaining a consistent local mirror of remote state: which messages exist, which flags are set, which folders contain which messages.

When a sync is interrupted — a network drop, a process crash, a device restart — the client needs to resume correctly. Over-fetching wastes bandwidth. Under-fetching produces a stale local state. Most clients handle this with a conservative fallback that re-fetches more than necessary. That is acceptable for small inboxes. For inboxes with hundreds of thousands of messages, it creates unacceptable sync overhead.

CONDSTORE and QRESYNC are the protocol extensions designed to solve this. They allow efficient delta syncing: the client can ask the server 'what changed since my last known state?' and receive only the delta. Implementing these correctly, with proper fallback for servers that don't support them, is the right approach for a production IMAP client.

How this shows up in product outcomes

When IMAP complexity is handled well, users see provider flexibility, reliable cross-account behavior, and better offline continuity. When it is not, they see inconsistent search and fragile multi-account workflows.

The difference between a client that 'supports IMAP' and a client that does IMAP correctly is invisible to most users until it breaks. Then it is very visible. Sync failures, missing messages, flags that don't propagate, search results that miss obvious matches — these are the symptoms of a shallow IMAP implementation.

For adjacent context, read Offline-First Landscape, Email Is Not Broken, and Why Apple Mail Search Feels Bad.