Usage Limits

The Gmail API is subject to a daily usage limit that applies to all requests made from your application, as well as per-user rate limits. The following table details the main request limits:

API Limit Type Limit
Daily Usage 1,000,000,000 quota units per day
Per User Rate Limit 250 quota units per user per second, moving average (allows short bursts)

Exceeding a rate limit will cause an HTTP 403 or HTTP 429 Too Many Requests response and your app should respond by retrying with exponential backoff.

To view or change usage limits for your project, or to request an increase to your quota, do the following:

  1. If you don't already have a billing account for your project, then create one.
  2. Visit the Enabled APIs page of the API library in the API Console, and select an API from the list.
  3. To view and change quota-related settings, select Quotas. To view usage statistics, select Usage.

Using batching is encouraged, however, larger batch sizes are likely to trigger rate limiting. Sending batches larger than 50 requests is not recommended.

Per-method quota usage

The daily usage limit is allocated as a number of usage units. The number of quota units consumed by a request varies depending on the method called. The following table outlines the per-method quota usage:

Method Quota Units
drafts.create 10
drafts.delete 10
drafts.get 5
drafts.list 5
drafts.send 100
drafts.update 15
getProfile 1
history.list 2
labels.create 5
labels.delete 5
labels.get 1
labels.list 1
labels.update 5
messages.attachments.get 5
messages.batchDelete 50
messages.delete 10
messages.get 5
messages.import 50
messages.insert 25
messages.list 5
messages.modify 5
messages.send 100
messages.trash 5
messages.untrash 5
settings.filters.create 5
settings.filters.delete 5
settings.filters.get 1
settings.filters.list 1
settings.forwardingAddresses.create 100
settings.forwardingAddresses.delete 5
settings.forwardingAddresses.get 1
settings.forwardingAddresses.list 1
settings.getAutoForwarding 1
settings.getImap 1
settings.getPop 1
settings.getVacation 1
settings.sendAs.create 100
settings.sendAs.delete 5
settings.sendAs.get 1
settings.sendAs.list 1
settings.sendAs.update 100
settings.sendAs.verify 100
settings.updateAutoForwarding 5
settings.updateImap 5
settings.updatePop 100
settings.updateVacation 5
stop 50
threads.delete 20
threads.get 10
threads.list 10
threads.modify 10
threads.trash 10
threads.untrash 10
watch 100

Gmail Per-User Limits

The Gmail API is also subject to Gmail per-user limits consistent with other Gmail interfaces, including:

Mail Sending Limits

The Gmail API enforces the standard daily mail sending limits (these limits differ for paying G Suite users vs free gmail.com users).

These limits are per-user and are shared by all of the user's clients, whether API clients, native/web clients or SMTP MSA. If these limits are exceeded a HTTP 429 Too Many Requests "User-rate limit exceeded" error mentioning "(Mail sending)" is returned with a time to retry. Note that daily limits being exceeded may result in these types of errors for multiple hours before the request is accepted, so your client may retry the request with standard exponential backoff.

These per-user limits cannot be increased for any reason.

The mail sending pipeline is complex: once the the user exceeds their quota, there can be a delay of several minutes before the API begins to return 429 error responses. So you cannot assume that a 200 response means the email was successfully sent.

Bandwidth Limits

The API has per-user upload and download bandwidth limits that are the equal to, but independent of, IMAP. These limits are quite generous and are shared across all Gmail API clients for a given user.

These limits are typically only hit in exceptional or abusive situations. If these limits are exceeded a HTTP 429 Too Many Requests "User-rate limit exceeded" error is returned with a time to retry. Note that daily limits being exceeded may result in these types of errors for multiple hours before the request is accepted, so your client may retry the request with standard exponential backoff.

These per-user limits cannot be increased for any reason.

Concurrent Requests

The Gmail API enforces a per-user concurrent request limit (in addition to the per-user rate limit). This limit is shared by all Gmail API clients accessing a given user and ensures that no API client is overloading a Gmail user mailbox or their backend server.

Making many parallel requests for a single user or sending batches with a large number of requests can trigger this error--as can a large number of independent API clients accessing the Gmail user mailbox simultaneously. If this limit is exceeded a HTTP 429 Too Many Requests "Too many concurrent requests for user" error is returned. Your client may retry the request with standard exponential backoff.

This per-user limit cannot be increased for any reason.

Send feedback about...