Gmail API
Gmail API
Gmail API lets apps read, send, and organize mail on behalf of a Google account — the core entry point for Workspace integrations.
Generous quotas — 1 billion quota units per user per day
Requires the OAuth flow — no simple API key option
Create a project at console.cloud.google.com, enable Gmail API, configure the OAuth consent screen and credentials. In code, run the OAuth 2.0 flow to get an access_token, then call https://gmail.googleapis.com/gmail/v1/users/me/... endpoints with scopes like https://www.googleapis.com/auth/gmail.readonly.
Uptime · 30-day window
About this API
The Gmail API is one of the most-used APIs in the Google Workspace ecosystem, exposing the full mailbox programming surface: read and write messages, manage labels, manipulate drafts, query Gmail search syntax, and subscribe to inbox events. Compared with IMAP/SMTP, the Gmail API is a structured JSON interface with higher quotas and incremental change tracking instead of polling.
Authentication is OAuth 2.0 only. You register an OAuth client in Google Cloud Console, run the user-consent flow, and store a refresh_token for long-term access. Workspace domain admins can also enable domain-wide delegation for a service account — ideal for org-wide internal tools.
Message bodies are base64url-encoded RFC 2822 MIME — parsing attachments or HTML content means walking the MIME tree. The History endpoint supports incremental sync (full fetch once, then pull only changes via history_id). Push notifications via Pub/Sub deliver real-time inbox events, eliminating the need for repeated long-polling. Quotas are measured in quota units (5 per read, 100 per send), and a user has 1 billion units per day — plenty of headroom for almost any app.
What you can build
- 1Build email clients or smart inbox tools
- 2Sync important emails into a CRM or ticketing system
- 3Apply rules to auto-archive, label, or forward messages
- 4Provide a "send via Gmail" compliant channel inside an app
- 5Generate email summaries and reply suggestions
Strengths & limitations
Strengths
- Generous quotas — 1 billion quota units per user per day
- Push notifications via Pub/Sub for real-time inbox events
- Shared OAuth scope model with other Workspace APIs (Calendar, Drive)
Limitations
- Requires the OAuth flow — no simple API key option
- Message bodies are base64url-encoded MIME — parsing takes work
- Send rates are anti-abuse capped (~250 emails/sec/account)
Example request
curl https://google.com/<endpoint> \
-H "Authorization: Bearer $ACCESS_TOKEN"Getting started
Create a project at console.cloud.google.com, enable Gmail API, configure the OAuth consent screen and credentials. In code, run the OAuth 2.0 flow to get an access_token, then call https://gmail.googleapis.com/gmail/v1/users/me/... endpoints with scopes like https://www.googleapis.com/auth/gmail.readonly.
FAQ
Is the Gmail API paid?+
Free to use; quotas are measured in quota units and most apps never come close to the cap.
Can my service account send mail without user consent?+
Only inside Google Workspace via domain-wide delegation, where an admin authorizes the service account to act on behalf of users.
How do I subscribe to new mail?+
Use the Watch API to attach a Pub/Sub topic; new mail fires a push, then call history.list to retrieve changes.
Does the OAuth consent screen need Google review?+
Apps using sensitive scopes (like gmail.readonly) require Google verification before public launch — usually 2–6 weeks.
Technical details
- Auth type
- oauth
- Pricing
- free
- Protocols
- REST
- SDKs
- python, javascript, java, go, ruby
- Response time
- 42 ms
- Last health check
- 5/12/2026, 7:37:31 AM
Endpoints
Parsed from the OpenAPI spec. Showing 12 of 79 non-deprecated endpoints.
/gmail/v1/users/{userId}/draftsusers/gmail/v1/users/{userId}/draftsusers/gmail/v1/users/{userId}/drafts/{id}users/gmail/v1/users/{userId}/drafts/{id}users/gmail/v1/users/{userId}/drafts/{id}users/gmail/v1/users/{userId}/drafts/sendusers/gmail/v1/users/{userId}/historyusers/gmail/v1/users/{userId}/labelsusers/gmail/v1/users/{userId}/labelsusers/gmail/v1/users/{userId}/labels/{id}users/gmail/v1/users/{userId}/labels/{id}users/gmail/v1/users/{userId}/labels/{id}users67 more endpoints not shown. See the OpenAPI spec for the full list.
More from Google
Google Workspace Admin SDK API programmatically manages Workspace organizations — users, groups, devices, domains, audit logs, organizational units.
Retrieve AdMob accounts, apps, ad units, ad sources, and generate mediation or network reports.
Work with AdSense Host accounts, ad clients, ad units, reports, and ad code generation from one API surface.
Programmatically manage Apigee organizations, API proxy deployments, attributes, certificates, and hybrid operations.
Google BigQuery API is the REST interface to GCP's flagship data warehouse — execute SQL queries, manage datasets/tables, stream inserts, and use built-in ML.
Control Binary Authorization attestors and policy checks for container images deployed to GKE and Anthos.
Fetch Business Profile location metrics, daily time series, and monthly search keyword impressions.
Google Calendar API lets apps create, read, and update calendar events programmatically — the go-to integration for scheduling apps.