Gmail API rate limits and quota, explained

The Gmail API is Google's official interface, not IMAP or SMTP scraping

The Gmail API is a REST interface that Google publishes and documents for third-party apps. It is a different technology from IMAP or SMTP, the older mail protocols used by generic email clients.

Clean Email only supports Gmail (personal @gmail.com and Google Workspace accounts) because it is built specifically against this API. Outlook, Yahoo Mail, iCloud Mail and other generic IMAP inboxes are not supported for the same reason.

• Access is granted through Google OAuth 2.0 sign-in — Clean Email never sees or stores a Google password.
• Every action (scanning, counting, deleting) goes through a documented Gmail API endpoint, not a raw protocol connection.
• Because it's the same API Google exposes to any developer, Clean Email is subject to the same published rate limits as every other Gmail API app.

Which Gmail API endpoints Clean Email calls

A cleanup uses a small set of endpoints, each documented in Google's Gmail API reference.

• messages.list — finds the IDs of messages that match Clean Email's scan query, the single query that excludes protected mail (for example -is:starred -has:attachment -in:sent). It returns IDs only, not message content.
• messages.get (metadata format) — fetches only headers, labels, size and thread ID for each message. Clean Email never requests the message body.
• messages.trash / batchModify — the default deletion path: moves matching messages into Gmail Trash, where they stay recoverable for 30 days.
• messages.batchDelete — used only for the optional, explicit permanent-delete opt-in, as documented in Google's batch delete guide. This is irreversible.

Gmail API quota units and per-second limits

The Gmail API doesn't just count requests — it charges each call in 'quota units,' and cheap calls cost less than expensive ones. Google's Gmail API reference is the authoritative source for current values; the figures below are what it publishes.

• Google can revise these per-method costs over time — always treat the Gmail API reference as the current source of truth, not this page.

How Clean Email's chunked processing stays inside the quota

A mailbox with tens of thousands of emails cannot be cleaned in one giant API call without risking the per-second quota limit. Clean Email splits large cleanups into smaller chunks instead of firing every request at once.

If Gmail responds with a rate-limit error on a given call, Clean Email retries that chunk rather than aborting the whole cleanup. This is why a very large mailbox may take longer to finish, in visible stages, rather than completing instantly — it's expected behavior, not a failure.

FAQ

What is the Gmail API rate limit?

Google's published default is 250 quota units per user per second, measured as a moving average, so brief bursts above that number are allowed. Each Google Cloud project also has its own overall daily quota, which can be viewed and increased in Google Cloud Console. See Google's Gmail API reference for the current figures.

Does Clean Email use IMAP or SMTP to access my Gmail?

No. Clean Email connects to Gmail exclusively through Google's official Gmail API using OAuth sign-in. It never logs into an IMAP or SMTP server and never scrapes your inbox directly.

How many quota units does deleting emails cost?

Reading calls like messages.list and messages.get cost a small number of quota units each (5 units per call, per Google's published table), while a bulk action like messages.batchDelete costs more per call (50 units) because it can act on many messages at once. Google can update these figures, so its Gmail API reference is the authoritative source.

Why does a big Gmail cleanup take longer than expected?

Very large mailboxes are processed in chunks instead of one giant request, so the cleanup stays under Gmail's per-second and per-project quota limits. That means a huge cleanup finishes in stages rather than instantly, but it also means it won't fail or get throttled outright.

What happens if Gmail throttles a request during a cleanup?

Gmail's API returns a rate-limit error if a caller exceeds its quota at a given moment. Clean Email's chunked processing is built to stay under those limits and retries the affected chunk automatically rather than aborting the run, so a temporary throttle doesn't cause a failed cleanup or data loss.

Can Clean Email clean Outlook, Yahoo Mail or iCloud Mail the same way?

No. Clean Email only supports Gmail — personal @gmail.com accounts and Google Workspace accounts — through the Gmail API. Outlook, Yahoo Mail, iCloud Mail and other generic IMAP inboxes are not supported.