# How to Automate Gmail Inbox Sorting using the API

- Tool: API Automations
- Difficulty: Intermediate
- Fix time: 30-60 minutes
- Compatibility: OAuth 2.0 required | gmail.modify scope needs OAuth verification + CASA audit | Google Cloud project required
- Last updated: May 2026

## TL;DR

Automate Gmail inbox sorting using the Gmail API's users.settings.filters.create endpoint to apply labels to future emails, and users.messages.batchModify to re-sort existing messages. Key auth requires OAuth 2.0 with gmail.settings.basic + gmail.modify scopes (both Restricted, requiring OAuth verification). Watch the per-user quota: batchModify costs 50 units per call against a 15,000 units/minute limit.

## Best practices

- Always create filters before running retroactive sorting — otherwise the filter creation quota cost (5 units) is wasted on messages already sorted
- Use Gmail's native search syntax in filter criteria: 'list:' reliably matches mailing lists, 'has:attachment larger:5M' catches large files
- Test filter criteria in Gmail's search bar before creating filters via API — what you see is what the API will match
- Handle the case where a label already exists: call labels.list and reuse existing IDs rather than failing on duplicate creation
- Use batchModify's 1,000-message limit aggressively — it's 50 quota units per call regardless of how many messages are in the batch
- For Workspace deployments, prefer Service Account + DWD over per-user OAuth to avoid managing thousands of refresh tokens
- Log all filter IDs created by your automation so you can programmatically clean them up later

## Frequently asked questions

### Do Gmail API filters apply to existing messages in my inbox?

No. users.settings.filters.create only applies to future incoming email. To sort existing messages, you must separately use users.messages.list with a search query to get message IDs, then call users.messages.batchModify to apply labels. The complete automation script above handles both steps.

### Is the Gmail API free?

The Gmail API itself is free with no per-call charges. However, using Restricted scopes (gmail.modify, gmail.readonly) requires completing Google's OAuth verification process and potentially a CASA security assessment, which can have associated costs for the audit. Compute costs for running your automation server are separate.

### What happens when I hit the rate limit?

You'll receive a 403 userRateLimitExceeded or 429 Too Many Requests error. The per-user limit is 15,000 quota units per minute. batchModify costs 50 units per call, so you can run about 300 batch calls per minute. Implement exponential backoff: wait 2^n seconds (starting at 1s, max 64s) and retry.

### Can I use a Service Account instead of OAuth for Gmail?

Yes, for Google Workspace (G Suite) organizations only. You need to enable Domain-Wide Delegation: create a Service Account in Google Cloud Console, enable DWD in Workspace Admin Console → Security → API Controls, and use setSubject() or with_subject() to impersonate a user. Personal Gmail accounts cannot use Service Accounts — they require 3-legged OAuth.

### Why does my OAuth token expire after 7 days?

When your OAuth consent screen is in 'Testing' mode, Google issues refresh tokens that expire after 7 days. To get long-lived tokens, publish your OAuth consent screen (you don't need to submit for verification to go from Testing to Published for Internal Workspace apps). External apps need verification before publishing.

### What's the difference between filter criteria 'from' vs 'query' fields?

The 'from' field is a simple sender match. The 'query' field accepts full Gmail search syntax including operators like 'list:', 'has:attachment', 'larger:5M', 'subject:', 'to:', and boolean operators. For complex matching, always use 'query' — it's the same search language you type in Gmail's search bar.

### Can RapidDev help build a custom Gmail integration?

Yes. RapidDev has built 600+ apps including email automation systems. Whether you need inbox sorting, lead capture pipelines, or full support triage with CRM integration, we can scope and build it. Contact us for a free consultation at rapidevelopers.com.

---

Source: https://www.rapidevelopers.com/api-automations/how-to-automate-gmail-inbox-sorting-using-the-api
© RapidDev — https://www.rapidevelopers.com/api-automations/how-to-automate-gmail-inbox-sorting-using-the-api