---
title: "Gmail API vs IMAP for developers · Workwae"
description: "Gmail API or IMAP: OAuth scopes and XOAUTH2, app passwords, history.list and Pub/Sub versus IDLE and CONDSTORE, quotas, labels as folders and sending."
url: https://workwae.com/blog/gmail-api-vs-imap
---

Blog

# Gmail API vs IMAP: authorization, sync, quotas and labels.

Both reach the same mailbox. They differ in how you are authorized, how you notice changes, which limit you hit first and how labels look.

November 18, 2026 · 8 min read

- [Gmail](https://workwae.com/blog/tag/gmail)
- [Sync and push](https://workwae.com/blog/tag/sync)
- [OAuth](https://workwae.com/blog/tag/oauth)

Gmail speaks two languages to outside software: a REST API and standard IMAP, with SMTP for sending. Both reach the same mailbox. They differ in how you get authorized, how you notice changes, what limits you hit and how labels look. The right choice is usually decided by the first of those.

This post compares them from Google’s documentation, links the sources, and ends with how Workwae uses each. Quota and policy numbers are as read on October 30, 2026 and change.

## Authorization: scopes, XOAUTH2 and app passwords.

**The Gmail API** offers a ladder of scopes. `gmail.send` is a sensitive scope. The ones that read mail (`gmail.readonly`, `gmail.modify`, `gmail.compose`, `gmail.metadata`) are restricted, as is the full `https://mail.google.com/` ([Gmail API scopes](https://developers.google.com/workspace/gmail/api/auth/scopes)). An app that uses restricted scopes and stores the data on its servers has to pass an annual security assessment based on the App Defense Alliance’s [CASA](https://workwae.com/glossary#casa) framework, and revalidate every year ([Security assessment](https://support.google.com/cloud/answer/13465431)).

**IMAP** has one [OAuth scope](https://workwae.com/glossary#oauth-scope): `https://mail.google.com/`, which reads, composes, sends and permanently deletes. The same scope covers POP and SMTP. Google says that to be approved the app “must show full utilization” of it, and that an app which does not need it should move to the Gmail API and its more granular scopes ([OAuth 2.0 mechanism](https://developers.google.com/workspace/gmail/imap/xoauth2-protocol)). So IMAP is not a way around verification. It is the same assessment with a broader scope.

The wire format is SASL XOAUTH2: the client sends `base64("user=" + user + "^Aauth=Bearer " + token + "^A^A")` in `AUTHENTICATE` (IMAP) or `AUTH` (SMTP). A session authenticated with OAuth lasts about as long as the access token, usually an hour, while a plain IMAP session lasts about 24 hours ([IMAP, POP and SMTP](https://developers.google.com/workspace/gmail/imap/imap-smtp)). A long-lived IMAP client therefore reconnects with a fresh token on a schedule.

**App passwords** are the password-shaped alternative for IMAP. Google says they “aren’t recommended and are unnecessary in most cases”. They need 2-Step Verification on, they are revoked when the account password changes, and the option may be missing on work or school accounts ([Sign in with app passwords](https://support.google.com/accounts/answer/185833)). Treat them as a fallback for an account whose owner cannot do OAuth.

Two OAuth rules apply to both paths. An app left in Testing status with an external audience gets refresh tokens that expire in 7 days, and a [refresh token](https://workwae.com/glossary#refresh-token) that carries Gmail scopes stops working when the user changes their password ([Using OAuth 2.0 to access Google APIs](https://developers.google.com/identity/protocols/oauth2)). Plan a reconnect flow either way.

## Sync: history and Pub/Sub versus UIDs and IDLE.

The Gmail API’s sync model has two modes. A _full sync_ lists message ids with `messages.list`, fetches each with batched `messages.get` calls and stores the mailbox’s `historyId`. A _partial sync_ calls `history.list` with that id and returns what was added, deleted or relabeled since. Records are typically kept for at least a week, sometimes much less, and an id outside the range gets `404`, which means a full sync again ([Synchronize clients with Gmail](https://developers.google.com/workspace/gmail/api/guides/sync)). To avoid polling, `users.watch` publishes to a Cloud Pub/Sub topic. The notification carries a cursor, not the change, and the watch must be renewed at least every 7 days. [Gmail push notifications](https://workwae.com/blog/gmail-push-notifications) covers that pipeline.

IMAP’s model is older and lower level. Each message in a folder has a UID, valid only for the folder’s `UIDVALIDITY` ([RFC 9051](https://www.rfc-editor.org/rfc/rfc9051)). Your client fetches UIDs and flags and diffs them against what it stored. Servers that support CONDSTORE and QRESYNC can return only what changed since a modification sequence, including vanished UIDs ([RFC 7162](https://www.rfc-editor.org/rfc/rfc7162)). Without them you compare everything. Push is `IDLE` ([RFC 2177](https://www.rfc-editor.org/rfc/rfc2177)), which holds a connection open and reports changes in the one selected folder. NOTIFY ([RFC 5465](https://www.rfc-editor.org/rfc/rfc5465)) can watch several folders, if the server offers it.

The practical differences:

- **Push needs infrastructure on the API side, and a socket on the IMAP side.** Pub/Sub means a topic, two IAM grants and a renewal loop. IDLE means one open connection per watched folder per account, which you keep alive through Gmail’s session limits.
- **Deltas are explicit on the API.** `history.list` names the change type. Over IMAP you infer it from UIDs and flags, and detecting a deletion depends on QRESYNC or a full UID comparison.
- **Gmail’s own extensions help.** `X-GM-MSGID` and `X-GM-THRID` give the same message and thread ids the API uses, in decimal ([IMAP extensions](https://developers.google.com/workspace/gmail/imap/imap-extensions)).

## Quotas and limits.

The two meters count different things. The API counts _quota units_: 1,200,000 per minute per project and 6,000 per minute per user. Costs vary by method: `history.list` is 2, `messages.list` 5, `messages.get` 20 (60 for `full` or `raw`), `messages.send` 100 and `watch` 100. Google also sets a daily billing threshold of 80 million units per project and says it plans to charge for usage above its thresholds later in 2026 ([Usage limits](https://developers.google.com/workspace/gmail/api/reference/quota)).

IMAP counts bytes. Workspace accounts have an IMAP download limit of 2,500 MB a day and an upload limit of 500 MB. Hitting one suspends the account’s IMAP access, typically for an hour and up to 24 hours. Google advises keeping each account to 500 labels and avoiding several clients on one account, since each downloads every message again ([Gmail bandwidth limits](https://knowledge.workspace.google.com/admin/gmail/gmail-bandwidth-limits)).

So a large first sync is a quota problem on the API (spread it, use batches and backoff) and a bandwidth problem on IMAP (fetch bodies lazily, not every message at once). Sending has its own per-mailbox limits, separate from API quota, and the API allows at most 500 recipients per message.

## Labels versus folders.

Gmail has labels, and a message can carry several. The API exposes them directly: `labelIds` on each message, `messages.modify` to add or remove them, and threads as a first-class object.

IMAP shows labels as folders. Google says Gmail “treats labels as folders for the purposes of IMAP”, so one message can appear in INBOX, in a user label and in `[Gmail]/All Mail`, each time with its own UID. System labels are prefixed `[Gmail]`, and special-use attributes such as `\All`, `\Sent` and `\Trash` mark them ([IMAP extensions](https://developers.google.com/workspace/gmail/imap/imap-extensions)). A client that treats each folder as a separate store stores the same message several times. Deduplicate on `X-GM-MSGID`, and read `X-GM-LABELS` to see a message’s labels without selecting every folder.

Users can also hide a label from IMAP with “Show in IMAP”. Only a service account authorized with the `gmail.imap_admin` scope sees every label regardless, so an IMAP client otherwise sees just the labels the user left visible.

## Sending.

The API’s `messages.send` takes a base64url RFC 2822 message in `raw`, and a reply can name a `threadId`. Over SMTP at `smtp.gmail.com`, with XOAUTH2 or an app password, there is no thread field. Gmail saves the Sent copy itself, and Google tells IMAP clients not to upload their own ([Recommended IMAP client settings](https://support.google.com/mail/answer/78892)). [Sending mail as your users](https://workwae.com/blog/sending-mail-as-your-users) walks through [Message-ID](https://workwae.com/glossary#message-id), In-Reply-To, References and `threadId`.

The API also has first-class drafts (`drafts.create` costs 10 units, `drafts.send` 100). Over IMAP a draft is a message you `APPEND` to the Drafts folder with the `\Draft` flag.

## When each fits.

- **Use the Gmail API** for new work on Gmail and Google Workspace accounts: narrower scopes, explicit history, native threads and labels, Pub/Sub push, and a quota you can read. Google’s own advice for apps that do not need full access points the same way.
- **Use IMAP** when the same code must talk to non-Gmail servers, when your app is already an IMAP client and the full mail scope is acceptable, or when a Gmail user can only give you an app password.
- **Use both** if you serve mixed customers: the API for Gmail, IMAP for everything else, behind one interface so the rest of your code never sees the difference.

## How Workwae handles both.

- **Gmail API by default.** A Gmail account connects through the Gmail API, with push over Pub/Sub (Workwae’s topic for its own app, yours for a customer app) and polling when Google refuses the watch. Mail sync replays `history.list` and rereads the mailbox on a `404`. Workwae’s own Google app asks for `gmail.modify`, not the full mail scope, so permanent delete is refused there and trash works ([Gmail provider](https://workwae.com/providers/gmail)).
- **Labels stay labels.** Each mailbox has a `kind`: `folder`, where a message is in exactly one, or `label`, where it can carry several, as on Gmail. A message update adds or removes up to 50 Gmail labels at a time ([mail guide](https://docs.workwae.com/guides/mail)).
- **IMAP for any other server.** Changes use QRESYNC when the server offers it and UID and flag diffs otherwise, and Workwae listens with IDLE or NOTIFY where supported and polls where not. Your app gets the same signed webhooks either way ([IMAP provider](https://workwae.com/providers/imap)).
- **Gmail over IMAP is opt-in and uses your app.** Add `mailAccess: "imap"` to a connect session and sign-in creates an IMAP account that authenticates with XOAUTH2. It needs your own Google OAuth app, because Workwae’s app refuses it with `google_imap_requires_own_app`, and the account has mail scopes only, with no calendar and no contacts. Password accounts, including Gmail app passwords, use `POST /v1/imap-accounts`, which checks the login before storing anything ([IMAP guide](https://docs.workwae.com/guides/imap)).
- **Reconnects are explicit.** An IMAP account whose password changed goes to `reauth_required`, and `PATCH /v1/accounts/{accountId}/imap-settings` with the new password brings it back.

gmail-over-imap.tsgmail-over-imap.py

```ts
const { authorizeUrl } = await workwae.oauthAuthorizations.create({
  provider: "google",
  oauthAppId: googleAppId, // your own app: Workwae's refuses IMAP
  redirectUri: "https://app.example.com/mail/connected",
  options: { mailAccess: "imap" },
});
```

```python
authorization = workwae.oauth_authorizations.create(
    provider="google",
    oauth_app_id=google_app_id,  # your own app: Workwae's refuses IMAP
    redirect_uri="https://app.example.com/mail/connected",
    options={"mail_access": "imap"},
)
print(authorization.authorize_url)
```

## Limits.

- **Workwae’s Google app has not completed CASA.** Restricted Gmail scopes on your own app need your own verification.
- **Gmail IMAP accounts are mail only.** Calendar and contacts need the Gmail API connection and their own scopes.
- **Push needs your Cloud project on your own app.** With your own Google app, the Pub/Sub topic lives in that project and its usage is billed there. Until it is set up, those accounts are polled.
- **IMAP push depends on the server.** Servers without IDLE or NOTIFY are polled, so changes arrive later.
- **Alpha SDKs.** `@workwae/sdk` is at 0.1.0-alpha and `workwae` at 0.1.0a2.

The [Connect flows guide](https://docs.workwae.com/guides/connect) shows how to register your own Google OAuth app, and [Connect](https://workwae.com/features/connect) covers the hosted sign-in pages.

## More from the blog.

### [Shared mailboxes in Microsoft 365 and Google Workspace.](https://workwae.com/blog/shared-mailboxes-microsoft-365-google-workspace)

November 16, 2026 · 6 min read

Shared mailboxes, Send As, Gmail delegation, send-as aliases, Google Groups and domain-wide delegation.

Tags: Microsoft Graph, Gmail, OAuth

### [Sending email from your users’ mailboxes: limits, bounces, tracking and merges.](https://workwae.com/blog/sending-email-from-your-users-mailboxes)

November 4, 2026 · 15 min read

Daily limits, authentication, the 5,000-a-day rules, bounces, suppression, validation, tracking, merges and retries.

Tags: Sending, Gmail, Microsoft Graph

### [Email and calendar webhooks you can trust.](https://workwae.com/blog/email-webhooks-you-can-trust)

October 26, 2026 · 7 min read

Signatures, duplicates, ordering, retries, replay and secret rotation for mail and calendar webhooks.

Tags: Webhooks, Sync and push
