IMAP vs the Gmail API: Why Some Email Clients Break Your Labels (and Charge a Subscription)

If you’ve tried a few Gmail apps, you’ve probably hit one of two problems. Some clients make a mess of your labels: duplicated messages, broken threading, a delete that doesn’t do what you expected. Others, often the most polished ones, will only sell you a subscription and flatly refuse a one-time purchase.

These look unrelated. They’re actually the same engineering decision, made in opposite directions. It all comes down to how the app talks to Gmail.

Two ways to connect

A mail client has two routes into a Gmail account.

IMAP is the open standard. It dates back to 1986, was standardised as IMAP4rev1 in RFC 3501, and got a full revision as recently as 2021 with IMAP4rev2 (RFC 9051). Essentially every provider speaks it: Gmail, Outlook, iCloud, Fastmail, your company’s mail server, the Dovecot box under someone’s desk.

The Gmail API is Google’s own REST interface. It isn’t a mail standard and doesn’t pretend to be one. It exposes Gmail’s actual data model directly, with labels, threads and change history as first-class objects, exactly as the web app sees them.

That one design difference produces both the label problem and the subscription problem.

Why labels get mangled

Gmail doesn’t have folders. It has labels, and one message can carry several at once. An email can sit in Inbox, Work and Receipts simultaneously. That’s one message with three tags, not three copies.

Classic IMAP assumes a message lives in exactly one folder. So when Gmail exposes a mailbox over IMAP, every label becomes a folder, the same message shows up in the folder for each of its labels, and everything also appears under All Mail. On the server it’s still a single message. To a naive client, though, each appearance looks like a separate email. Sync all folders and you download the same message four times, thread it four times, and display it four times. Delete it from one label-folder and you’ve only removed that label; the message stays in All Mail, which surprises people in the other direction.

That’s the entire origin of the “IMAP breaks Gmail” complaint. The wire carries everything a client needs to get this right; plenty of clients just don’t use it.

Because Gmail publishes IMAP extensions for exactly this, advertised under the X-GM-EXT-1 capability:

• X-GM-MSGID: a stable 64-bit ID that identifies the same message across every folder it appears in
• X-GM-THRID: the thread ID the Gmail web interface uses, so conversations group identically
• X-GM-LABELS: read and modify a message’s full label set directly, no folder pretence required
• X-GM-RAW: run Gmail’s own search syntax (has:attachment in:unread) through a standard IMAP SEARCH

A client that uses these can deduplicate by message ID, thread like the web app, and treat “move to folder” as “change labels”. Multi-label mail works fine over IMAP. It just takes deliberate engineering rather than pointing a generic folder-syncing client at imap.gmail.com.

What the API genuinely does better

Fairness first: the Gmail API earns its keep on sync mechanics. Every mailbox change gets a historyId, and one call to history.list returns everything that changed since the last ID you saw. Push notifications arrive over Cloud Pub/Sub rather than holding a connection open per folder.

IMAP’s equivalents exist and work. IDLE provides push and is part of the base spec in IMAP4rev2, and CONDSTORE and QRESYNC (RFC 7162) provide incremental resync based on what changed rather than rescanning. Gmail’s own IMAP endpoint advertises CONDSTORE. The honest summary: a well-built API client can hold an edge on a very large mailbox, and a well-built IMAP client closes most of that gap. Neither has to be slow.

The subscription connection

Now the part rarely explained. Building only on the Gmail API means the whole product depends on Google’s proprietary interface, and that dependency has running costs and risks.

OAuth verification and the annual security assessment. Any app requesting restricted Gmail scopes (the ones needed to actually read and manage mail) must pass Google’s restricted scope verification. Apps that can access mail data from or through the developer’s own servers must additionally complete an independent security assessment under the CASA framework, revalidated every twelve months. Assessor pricing currently runs from roughly $500 to $1,000 a year at Tier 2 up to several thousand at Tier 3, before counting the engineering time to remediate findings. That recurring bill has pushed some small developers to drop Gmail support entirely. One nuance worth knowing: a purely local client that never routes mail through a third-party server can avoid the assessment itself, though the rest of the verification process still applies.

Quota and platform risk. Mimestream, the best-known Gmail-API client, is refreshingly direct about this in its own explanation of subscription licensing. It manages a limited fleet-wide API quota granted by Google, has to track API changes it doesn’t control, and won’t sell lifetime licences because, in its own words, the Twitter and Reddit APIs recently went from free to paid. Those are real risks and Mimestream is right to name them. They also exist purely because of the protocol choice.

Gmail, and only Gmail. The Gmail API cannot see an Outlook, iCloud or work IMAP account. A client built solely on it is a Gmail-only tool by design, so you keep a second client around for everything else.

Add it up and a subscription stops looking like greed. It’s a reasonable way to fund a permanent, Google-shaped liability. But it’s a liability the developer chose, and as a customer you inherit it: paying monthly, indefinitely, for one provider.

The third option: IMAP done properly

The usual framing offers you mangled labels or subscription lock-in. It skips the option of an IMAP client that actually implements Gmail’s extensions.

Handled that way, a drag between views becomes a label change rather than a destructive move, so one email can live in several places at once, exactly as the API would model it. Conversations group by X-GM-THRID. Search passes through X-GM-RAW, so from:amazon has:attachment behaves as it does on the web. No duplicates, no surprise deletes.

And because it’s standard IMAP underneath, you keep what the API structurally can’t offer. The same client works with Outlook, iCloud, Fastmail and any plain IMAP account, all in one place. There’s no Gmail-API quota or annual assessment baked into the architecture, which is why a one-time licence remains a viable business model. And mail flows directly between your machine and the mail server, with no relay in the middle.

Is Google killing IMAP?

No, though it did kill password-only sign-in. Google Workspace stopped accepting basic username-and-password access for IMAP, SMTP, POP, CalDAV and CardDAV in 2025; personal accounts still allow app passwords, provided 2-Step Verification is on. The supported route for third-party clients is OAuth 2.0 over IMAP, which Google continues to maintain alongside the API. The protocol itself is far from abandoned either; IMAP4rev2 landed in 2021. IMAP with OAuth is the sanctioned, current way to reach Gmail from outside.

How to choose

• Gmail-only, on a Mac, and raw native-Gmail sync speed matters more than anything else? A Gmail-API client is a reasonable pick. Go in knowing it’s Gmail-only and subscription-funded, for the structural reasons above.
• More than one account or provider, or you’d rather own your client outright? A label-aware IMAP client is the better fit, and there’s no technical reason it should mangle your labels.

FAQ

Is IMAP “old and slow”? Old, yes, and that’s mostly a feature: it’s a stable standard every provider supports, still actively maintained (the current revision is from 2021). “Slow” describes lazy implementations and legacy polling, not modern IMAP with IDLE push and CONDSTORE incremental sync.

Does an IMAP client have to break Gmail labels? No. Broken labels are the signature of a client that ignored X-GM-EXT-1. A label-aware client handles multi-label mail correctly over IMAP.

Why is Mimestream subscription-only? Its stated reasons are dependence on the Gmail API: a limited fleet-wide quota from Google, API changes outside its control, and the risk that the API’s terms change the way Twitter’s and Reddit’s did. Legitimate reasoning, and also a permanent monthly cost for a Gmail-only tool. There’s a fuller comparison at Kanmail vs Mimestream.

Can one client handle Gmail, Outlook and iCloud well? Yes, but only one built on the standards (IMAP/SMTP plus OAuth sign-in). The Gmail API can’t see non-Google accounts at all.

Mangled labels aren’t evidence that IMAP is bad; they’re evidence a client ignored the extensions Gmail ships for exactly that problem. And a subscription often isn’t greed; it’s the price of betting the whole product on Google’s API. Knowing the tradeoff lets you pick on purpose.

Kanmail takes the third path: label-aware IMAP/SMTP with Gmail-style search and copy-on-drag for multi-label workflows, OAuth sign-in so it never holds your password, every provider on one board, and a one-time licence with no subscription.

Related: The Case Against Subscription Email · How to Organise Gmail with Labels and Filters · Use Gmail as a kanban board