Limites de uso

A API Gmail está sujeita a limites de uso que restringem a taxa em que você pode chamar os métodos da API. Os limites são definidos em termos de unidades de cota, uma unidade de medida abstrata que representa o uso de recursos do Gmail.

Cotas da API Gmail

A API Gmail aplica dois tipos de cotas:

  • Por minuto por projeto na nuvem:é o número de unidades de cota que o projeto do Google Cloud pode usar em um minuto.

  • Por minuto por usuário por projeto:é o número de unidades de cota que um usuário específico pode usar no projeto na nuvem. Esse limite ajuda a garantir uma distribuição justa do uso entre os usuários.

A tabela a seguir detalha esses limites:

Tipo de limite de uso Limite
Por minuto e por projeto 1.200.000 unidades de cota
Por minuto, por usuário e por projeto 6.000 unidades de cota

Para informações sobre como lidar com erros de limite, consulte Resolver erros.

Limite para faturamento diário

Esse limite por dia por projeto define o número máximo de unidades de cota que seu projeto do Google Cloud pode usar em um período de 24 horas antes que as cobranças sejam aplicadas.

O uso abaixo desse limite não gera cobranças extras, e sua conta do Google Cloud não é faturada. O Google vai compartilhar todos os detalhes de faturamento ainda em 2026, com pelo menos 90 dias de antecedência antes que as mudanças entrem em vigor.

Não é possível solicitar um aumento desse limite diário.

A tabela a seguir detalha o limite:

Tipo de limite Limite
Por dia e por projeto 80.000.000 de unidades de cota

Para mais informações, consulte Modelo padronizado do Google Workspace para ferramentas e APIs de agentes.

Uso de cotas por método

O número de unidades de cota que cada solicitação consome varia de acordo com o método chamado e os parâmetros de consulta. A tabela a seguir descreve o uso da unidade de cota por método:

Método Unidades de cota
drafts.create 10
drafts.delete 10
drafts.get 20 (60 quando format é full, raw ou 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 quando format é full, raw ou 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 quando format é full)
threads.list 10
threads.modify 10
threads.trash 20
threads.untrash 10
watch 100

Ao usar a API Gmail, também há um limite de 500 destinatários por mensagem de e-mail.

Resolver erros de cota com base no tempo

Para todos os erros baseados em tempo (máximo de N solicitações por X minutos), recomendamos que seu código capture a exceção e use uma espera exponencial truncada para garantir que os dispositivos não gerem carga excessiva.

A espera exponencial é uma estratégia padrão de tratamento de erros para aplicativos de rede. Um algoritmo de espera exponencial repete solicitações usando tempos de espera exponencialmente crescentes entre as solicitações, até um tempo máximo de espera. Se as solicitações ainda não forem bem-sucedidas, é importante que os atrasos entre as solicitações aumentem ao longo do tempo até que a solicitação seja bem-sucedida.

Exemplo de algoritmo

Um algoritmo de espera exponencial repete solicitações exponencialmente, aumentando o tempo de espera entre novas tentativas até um tempo máximo de espera. Exemplo:

  1. Faça uma solicitação para a API Gmail.
  2. Se a solicitação falhar, aguarde 1 + random_number_milliseconds e tente novamente.
  3. Se a solicitação falhar, aguarde 2 + random_number_milliseconds e tente novamente.
  4. Se a solicitação falhar, aguarde 4 + random_number_milliseconds e tente novamente.
  5. E assim por diante, até um tempo maximum_backoff.
  6. Continue aguardando e tentando até um número máximo de novas tentativas, mas não aumente o período de espera entre elas.

em que:

  • O tempo de espera é min(((2^n)+random_number_milliseconds), maximum_backoff), com n incrementado em 1 para cada iteração (solicitação).
  • random_number_milliseconds é um número aleatório de milissegundos menor ou igual a 1.000. Isso ajuda a evitar casos em que muitos clientes são sincronizados por alguma situação e todos tentam novamente ao mesmo tempo, enviando solicitações em ondas sincronizadas. O valor de random_number_milliseconds é recalculado após cada nova tentativa de solicitação.
  • maximum_backoff costuma ser 32 ou 64 segundos. O valor adequado depende do caso de uso.

O cliente pode continuar tentando novamente depois de maximum_backoff. As novas tentativas após esse ponto não precisam continuar aumentando o tempo de espera. Por exemplo, se um cliente usa um tempo maximum_backoff de 64 segundos, depois de atingir esse valor, ele pode tentar novamente a cada 64 segundos. Em algum momento, os clientes são impedidos de tentar novamente infinitas vezes.

O tempo de espera entre novas tentativas e o número de novas tentativas depende do seu caso de uso e das condições da rede.

Preços

Todo o uso padrão da API Gmail está disponível sem custo financeiro adicional. Exceder os limites de solicitação de cota vai gerar cobranças na sua conta de faturamento do Google Cloud no final de 2026. Para mais informações, consulte o modelo padronizado do Google Workspace para ferramentas e APIs de agentes.

Solicitar aumento de cota

Dependendo do uso de recursos do projeto, talvez seja necessário solicitar um ajuste de cota. As chamadas de API feitas por uma conta de serviço são consideradas como se estivessem usando uma única conta. Solicitar uma cota ajustada não garante a aprovação. As solicitações de ajuste de cota que aumentam significativamente o valor da cota podem levar mais tempo para serem aprovadas.

Nem todos os projetos têm as mesmas cotas. À medida que você usa o Google Cloud com o tempo, os valores das cotas podem precisar aumentar. Caso espere um aumento de uso significativo, solicite o ajuste das cotas na página Cotas e limites do sistema no console do Google Cloud.

Para saber mais, consulte os seguintes recursos:

Cotas do servidor MCP do Gmail

O servidor MCP do Gmail usa uma métrica de alocação de custo de consulta. As tabelas a seguir detalham o custo de consulta para cada método de servidor MCP do Gmail por seção:

Cotas do MCP do Gmail

O servidor aplica dois tipos de cotas:

  • Por minuto por projeto:é o custo da consulta para seu projeto na nuvem por um minuto.

  • Por minuto, por usuário e por projeto:é o custo de consulta do seu projeto na nuvem por um minuto que qualquer usuário específico pode usar.

A tabela a seguir detalha essas cotas:

Tipo de limite de uso Custo da consulta
Por minuto e por projeto 1.200.000
Por minuto, por usuário e por projeto 6.000

Cotas do conjunto de ferramentas do MCP do Gmail

A tabela a seguir detalha o custo de consulta para cada conjunto de ferramentas do gmailmcp.googleapis.com:

Endpoint Ferramenta Custo da consulta

/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

Para mais informações, consulte a referência da API MCP do Gmail.