Лимиты на использование

Для Gmail API действуют ограничения на использование, которые ограничивают частоту вызова методов API. Ограничения задаются в единицах квоты – абстрактных единицах измерения, представляющих использование ресурсов Gmail.

Квоты Gmail API

Gmail API применяет два типа квот:

  • В минуту на проект. Количество единиц квоты, которое может использовать ваш проект Google Cloud за одну минуту.

  • В минуту на пользователя на проект. Это количество единиц квоты, которое может использовать любой пользователь в вашем облачном проекте. Это ограничение помогает обеспечить справедливое распределение использования между вашими пользователями.

В таблице ниже приведены ограничения для каждого типа.

Тип лимита на использование Ограничение
В минуту на проект 1 200 000 единиц квоты
На пользователя в минуту на проект 6000 единиц квоты

Подробнее о том, как устранять ошибки, связанные с ограничениями…

Порог оплаты за день

Этот лимит на день на проект определяет максимальное количество единиц квоты, которое ваш облачный проект Google Cloud может использовать в течение 24 часов до взимания платы.

Если вы не превысите этот порог, то плата за использование взиматься не будет и в вашем аккаунте Google Cloud не будет выставлен счет. Google предоставит полную информацию о выставлении счетов позже в 2026 году, не менее чем за 90 дней до вступления изменений в силу.

Запросить увеличение этого лимита нельзя.

В таблице ниже приведены ограничения.

Тип порогового значения Ограничение
На проект в день 80 000 000 единиц квоты

Дополнительную информацию можно найти в статье Стандартизированная модель Google Workspace для инструментов и API агентов.

Использование квоты для каждого метода

Количество единиц квоты, которое расходуется на каждый запрос, зависит от вызываемого метода и параметров запроса. В таблице ниже указано, сколько единиц квоты расходуется на каждый метод.

Метод Единицы квот
drafts.create 10
drafts.delete 10
drafts.get 20 (60, если format – это full, raw или html)
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 20
messages.batchDelete 50
messages.batchModify 50
messages.delete 10
messages.get 20 (60, если format – это full, raw или html)
messages.import 25
messages.insert 25
messages.list 5
messages.modify 5
messages.send 100
messages.trash 20
messages.untrash 5
settings.delegates.create 100
settings.delegates.delete 5
settings.delegates.get 1
settings.delegates.list 1
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 40 (120, если format – full)
threads.list 10
threads.modify 10
threads.trash 20
threads.untrash 10
watch 100

При использовании Gmail API также действует ограничение в 500 получателей на одно электронное письмо.

Как устранить ошибки, связанные с временными квотами

Для всех ошибок, связанных со временем (максимум N запросов за X минут), мы рекомендуем, чтобы ваш код перехватывал исключение и использовал усеченную экспоненциальную выдержку, чтобы ваши устройства не генерировали чрезмерную нагрузку.

Экспоненциальная выдержка – это стандартная стратегия обработки ошибок для сетевых приложений. Алгоритм экспоненциальной выдержки повторяет запросы, экспоненциально увеличивая время ожидания между ними до максимального значения. Если запросы по-прежнему не выполняются, важно, чтобы задержки между ними со временем увеличивались, пока запрос не будет выполнен.

Пример алгоритма

Алгоритм экспоненциальной выдержки повторяет запросы экспоненциально, увеличивая время ожидания между повторными попытками до максимального времени выдержки. Пример:

  1. Отправьте запрос к Gmail API.
  2. Если запрос не удается выполнить, подождите 1 + random_number_milliseconds и повторите попытку.
  3. Если запрос не удается выполнить, подождите 2 + random_number_milliseconds и повторите попытку.
  4. Если запрос не удается выполнить, подождите 4 + random_number_milliseconds и повторите попытку.
  5. и так далее, до maximum_backoff раз.
  6. Продолжайте ждать и повторять попытки до достижения максимального количества попыток, но не увеличивайте период ожидания между попытками.

где:

  • Время ожидания составляет min(((2^n)+random_number_milliseconds), maximum_backoff), где n увеличивается на 1 для каждой итерации (запроса).
  • random_number_milliseconds – случайное число миллисекунд,не превышающее 1000. Это позволяет избежать ситуаций, когда множество клиентов синхронизируются в определенный момент и все одновременно повторяют попытку, отправляя запросы синхронизированными волнами. Значение random_number_milliseconds пересчитывается после каждого повторного запроса.
  • maximum_backoff обычно составляет 32 или 64 секунды. Подходящее значение зависит от конкретного случая.

Клиент может продолжать попытки после достижения времени maximum_backoff. После этого увеличивать задержку не нужно. Например, если клиент использует время maximum_backoff, равное 64 секундам, то после достижения этого значения он может повторять попытку каждые 64 секунды. В какой-то момент клиенты должны прекратить попытки.

Время ожидания между повторными попытками и их количество зависят от вашего сценария использования и условий сети.

Цены

Стандартное использование Gmail API предоставляется бесплатно. Превышение лимитов на запросы квоты будет оплачиваться через платежный аккаунт Google Cloud. Это изменение планируется ввести в 2026 году. Дополнительную информацию можно найти в статье Стандартизированная модель Google Workspace для инструментов и API агентов.

Как запросить увеличение квоты

В зависимости от особенностей использования ресурсов в проекте может возникнуть необходимость запросить корректировку квоты. Вызовы API, выполняемые сервисным аккаунтом, считаются вызовами, выполняемыми одним аккаунтом. Запрос на изменение квоты может быть отклонен. Запросы на значительное увеличение квоты могут обрабатываться дольше.

Квоты могут различаться в зависимости от проекта. По мере того как вы будете все больше использовать Google Cloud, вам может потребоваться увеличить квоты. Если вы ожидаете значительного увеличения использования, вы можете заранее запросить корректировку квот на странице Quotas & System Limits (Квоты и системные лимиты) в консоли Google Cloud.

Дополнительную информацию можно найти в следующих ресурсах:

Квоты MCP-сервера Gmail

MCP-сервер Gmail использует показатель распределения стоимости запросов. В таблицах ниже приведены сведения о стоимости запросов для каждого метода сервера MCP Gmail по разделам.

Квоты MCP для Gmail

Сервер применяет два типа квот:

  • На один облачный проект в минуту. Стоимость запросов к вашему облачному проекту за одну минуту.

  • В минуту на пользователя на проект. Это стоимость запросов к вашему облачному проекту за одну минуту, которую может использовать любой пользователь.

В таблице ниже приведены сведения об этих квотах.

Тип лимита на использование Стоимость запроса
В минуту на проект 1 200 000
На пользователя в минуту на проект 6000

Квоты на инструменты MCP для Gmail

В таблице ниже указана стоимость запроса для каждого набора инструментов gmailmcp.googleapis.com.

Конечная точка Инструмент Стоимость запроса

/mcp/v1

create_draft

10

get_thread

40

label_message

10

label_thread

10

list_drafts

5

list_labels

1

search_threads

10

unlabel_message

10

unlabel_thread

10

Дополнительную информацию можно найти в справочнике по Gmail MCP API.