Limites de taxa e cota da API do Gmail, explicados

A API do Gmail é a interface oficial do Google, não scraping de IMAP ou SMTP

A API do Gmail é uma interface REST que o Google publica e documenta para aplicativos de terceiros. É uma tecnologia diferente do IMAP ou SMTP, os protocolos de e-mail mais antigos usados por clientes de e-mail genéricos.

O Clean Email só é compatível com o Gmail (contas pessoais @gmail.com e contas do Google Workspace) porque foi criado especificamente para essa API. Outlook, Yahoo Mail, iCloud Mail e outras caixas de entrada IMAP genéricas não são compatíveis pelo mesmo motivo.

• O acesso é concedido por meio do login do Google OAuth 2.0 — o Clean Email nunca vê nem armazena sua senha do Google.
• Cada ação (varredura, contagem, exclusão) passa por um endpoint documentado da API do Gmail, não por uma conexão de protocolo bruto.
• Por ser a mesma API que o Google disponibiliza a qualquer desenvolvedor, o Clean Email está sujeito aos mesmos limites de taxa publicados que qualquer outro app que use a API do Gmail.

Quais endpoints da API do Gmail o Clean Email usa

Uma limpeza usa um pequeno conjunto de endpoints, cada um documentado na referência da API do Gmail do Google.

• messages.list — encontra os IDs de mensagens que correspondem à consulta de verificação do Clean Email, a que exclui os emails protegidos (por exemplo, -is:starred -has:attachment -in:sent). Ele retorna apenas IDs, não o conteúdo das mensagens.
• messages.get (formato metadata) — busca apenas cabeçalhos, marcadores, tamanho e ID da conversa de cada mensagem. O Clean Email nunca solicita o corpo da mensagem.
• messages.trash / batchModify — o caminho de exclusão padrão: move as mensagens correspondentes para a Lixeira do Gmail, onde ficam recuperáveis por 30 dias.
• messages.batchDelete — usado apenas para a opção explícita e opcional de exclusão permanente, conforme documentado no guia de exclusão em lote do Google. Essa ação é irreversível.

Unidades de cota da API do Gmail e limites por segundo

A API do Gmail não apenas conta solicitações — ela cobra cada chamada em 'unidades de cota', e chamadas baratas custam menos do que as caras. A referência da API do Gmail do Google é a fonte oficial dos valores atuais; os números abaixo são os publicados por ela.

• O Google pode revisar esses custos por método ao longo do tempo — considere sempre a referência da API do Gmail como a fonte de verdade atual, não esta página.

Como o processamento em lotes do Clean Email permanece dentro da cota

Uma caixa de entrada com dezenas de milhares de e-mails não pode ser limpa em uma única chamada de API gigante sem arriscar ultrapassar o limite de cota por segundo. O Clean Email divide grandes limpezas em lotes menores em vez de disparar todas as solicitações de uma vez.

Se o Gmail responder com um erro de limite de taxa em uma determinada chamada, o Clean Email tenta novamente esse lote em vez de cancelar toda a limpeza. Por isso, uma caixa de entrada muito grande pode demorar mais para terminar, em etapas visíveis, em vez de concluir instantaneamente — isso é um comportamento esperado, não uma falha.

Perguntas frequentes

Qual é o limite de taxa da API do Gmail?

O valor padrão publicado pelo Google é de 250 unidades de cota por usuário por segundo, medido como média móvel, então picos breves acima desse número são permitidos. Cada projeto do Google Cloud também tem sua própria cota diária geral, que pode ser vista e aumentada no Google Cloud Console. Consulte a referência da API do Gmail do Google para os números atuais.

O Clean Email usa IMAP ou SMTP para acessar meu Gmail?

Não. O Clean Email se conecta ao Gmail exclusivamente pela API oficial do Gmail do Google usando login OAuth. Ele nunca faz login em um servidor IMAP ou SMTP nem faz scraping direto da sua caixa de entrada.

Quantas unidades de cota custa excluir e-mails?

Chamadas de leitura como messages.list e messages.get custam poucas unidades de cota cada uma (5 unidades por chamada, segundo a tabela publicada pelo Google), enquanto uma ação em massa como messages.batchDelete custa mais por chamada (50 unidades) porque pode agir em muitas mensagens de uma vez. O Google pode atualizar esses números, então a referência da API do Gmail é a fonte oficial.

Por que uma limpeza grande no Gmail demora mais do que o esperado?

Caixas de entrada muito grandes são processadas em lotes em vez de em uma única solicitação gigante, para que a limpeza permaneça dentro dos limites de cota por segundo e por projeto do Gmail. Isso significa que uma limpeza enorme termina em etapas em vez de instantaneamente, mas também evita que falhe ou seja totalmente bloqueada.

O que acontece se o Gmail bloquear uma solicitação durante uma limpeza?

A API do Gmail retorna um erro de limite de taxa se quem chama ultrapassa sua cota em um determinado momento. O processamento em lotes do Clean Email é criado para permanecer dentro desses limites e tenta novamente automaticamente o lote afetado em vez de cancelar a execução, então um bloqueio temporário não causa falha na limpeza nem perda de dados.

O Clean Email pode limpar Outlook, Yahoo Mail ou iCloud Mail da mesma forma?

Não. O Clean Email só é compatível com o Gmail — contas pessoais @gmail.com e contas do Google Workspace — pela API do Gmail. Outlook, Yahoo Mail, iCloud Mail e outras caixas de entrada IMAP genéricas não são compatíveis.