Limites de taxa de API de e-mail por provedor

Referências de comandos: nylas email list, nylas email send, nylas email search.

O que são os limites de taxa da Gmail API?

Os limites de taxa da Gmail API são medidos em unidades de cota (quota units), não em contagem bruta de requisições. Cada método da Gmail API custa um número diferente de unidades, e cada usuário recebe 250 unidades por segundo por padrão. Uma chamada messages.list custa 5 unidades, um messages.get custa 5 unidades e um messages.send custa 100 unidades. Isso significa que você pode enviar no máximo 2 mensagens por segundo por usuário, mas listar 50 páginas por segundo.

Segundo a documentação de cotas da Gmail API do Google, o limite de taxa por usuário foi atualizado em 1º de maio de 2026 para 250 unidades/usuário/segundo (antes, só havia controle de cotas diárias). O limite diário por projeto é de 1 bilhão de unidades de cota. Exceder qualquer um dos dois dispara um HTTP 429 com header Retry-After.

O sistema de unidades de cota significa que um loop de sync ingênuo que chama messages.list e depois messages.get em cada resultado queima 10 unidades por mensagem. Sincronizar 1.000 mensagens custa 10.000 unidades no total, o que um único usuário consegue esgotar em 40 segundos. Endpoints de batch reduzem a sobrecarga de round-trips, mas não mudam o custo unitário por mensagem. O CLI agrupa essas chamadas internamente e respeita os headers Retry-After, então um nylas email list --limit 1000 trata paginação e throttling sem nenhum código extra.

# List up to 200 Gmail messages — the CLI handles pagination and rate limits
nylas email list --limit 200 --json

Quais são os limites de taxa de e-mail do Microsoft Graph?

O Microsoft Graph impõe um throttle de 10.000 requisições por 10 minutos por app por caixa de correio. Isso equivale a cerca de 16 requisições por segundo por caixa. Quando você excede o limite, o Graph retorna HTTP 429 com um header Retry-After indicando quantos segundos esperar. Diferente do Gmail, o Graph não usa um sistema de custo por unidade; cada requisição conta como 1, independentemente da complexidade do endpoint.

Segundo a documentação de throttling da Graph API da Microsoft, o limite de 10.000/10 min se aplica aos endpoints de e-mail, calendário e contatos do Outlook. Limites por tenant são mais altos (não divulgados, variam por serviço). Requisições em batch via endpoint $batch contam como 1 requisição para o throttling, mas são limitadas a 20 operações por batch. O teto prático para sync de e-mail é de cerca de 3.200 mensagens por 10 minutos se cada mensagem exigir um GET separado.

O Graph também impõe um limite de envio de 10.000 destinatários por dia para contas business do Microsoft 365 e de 300 mensagens por dia para contas de consumo do Outlook.com. O que conta é o número de destinatários, não o de mensagens. Uma única mensagem para 50 destinatários consome 50 do limite diário.

O CLI abstrai esses limites atrás de um único comando. Rodar nylas email send contra uma caixa Outlook trata respostas 429 automaticamente e tenta de novo com o atraso especificado no header Retry-After.

# Send an email through Outlook — retries on 429 are handled by the CLI
nylas email send --to "recipient@example.com" --subject "Quarterly report" --body "Attached."

Como os limites de taxa se comparam entre provedores de e-mail?

A aplicação de limites de taxa varia muito entre os 5 principais provedores de e-mail. O Gmail usa unidades de cota com custos por método. O Microsoft Graph usa contagem simples de requisições. Yahoo e iCloud impõem limites de conexão não documentados no nível do IMAP. O Exchange EWS usa throttling de requisições simultâneas. A tabela abaixo mostra os números que mais importam para workflows de e-mail automatizados: requisições por segundo, mensagens por dia e tetos de tamanho de anexo.

A coluna "leituras efetivas/s" reflete o throughput realista de um padrão de sync list + get, não o máximo teórico da documentação do provedor. O sistema de unidades do Gmail o torna o mais permissivo para cargas com leitura intensa. O modelo de contagem simples do Graph é mais simples, porém mais restritivo para sync em massa. Yahoo e iCloud não publicam números exatos, então as estimativas acima vêm de testes empíricos com o CLI em contas de idades variadas.

Quais códigos de erro SMTP indicam limite de taxa?

Erros de limite de taxa caem em duas categorias: códigos de status HTTP de APIs REST e códigos de status estendidos SMTP de servidores de e-mail. A resposta HTTP 429 "Too Many Requests" é o sinal padrão da Gmail API e do Microsoft Graph. Servidores SMTP usam a família 4.7.x de códigos de status estendidos. Saber qual código você está vendo determina se deve tentar de novo imediatamente ou esperar horas.

A distinção entre códigos estendidos 4xx e 5xx importa. Um 4.7.28 do Gmail é temporário e se resolve sozinho. Um 5.7.3 do Exchange significa que você atingiu um teto diário rígido. Segundo a documentação de limites de envio do Google Workspace, contas Gmail gratuitas são limitadas a 500 mensagens por dia, enquanto contas Google Workspace recebem 2.000. O CLI interpreta esses códigos de erro e ajusta o comportamento de retry de acordo.

Como tentar de novo depois de atingir limites de taxa?

Backoff exponencial com jitter é a estratégia padrão de retry para limites de taxa de API de e-mail. O padrão dobra o tempo de espera após cada tentativa falha (1s, 2s, 4s, 8s) e adiciona um jitter aleatório de 0 a 1 segundo para evitar problemas de thundering herd quando vários clientes atingem o mesmo limite ao mesmo tempo. Sem jitter, retries sincronizados de workers paralelos se acumulam e estendem a janela de throttle.

Segundo a documentação de tratamento de erros de API do Google, o máximo recomendado é de 5 tentativas, com um teto de 32 segundos no intervalo de backoff. A documentação do Graph da Microsoft recomenda respeitar exatamente o valor do header Retry-After em vez de calcular seu próprio atraso. Na prática, o valor de Retry-After do Gmail costuma ficar entre 1-60 segundos, enquanto o Graph retorna 5-300 segundos, dependendo da severidade do throttle.

Se você chama a Gmail API ou a Graph API diretamente, precisa implementar esse loop por conta própria. O trecho Python abaixo mostra uma implementação mínima com jitter. Cada retry dobra o atraso base e adiciona até 1 segundo de jitter aleatório. Após 5 falhas, a função lança uma exceção em vez de repetir para sempre.

import time, random, requests

def call_with_backoff(url, headers, max_retries=5):
    delay = 1
    for attempt in range(max_retries):
        resp = requests.get(url, headers=headers)
        if resp.status_code != 429:
            return resp
        retry_after = int(resp.headers.get("Retry-After", delay))
        jitter = random.uniform(0, 1)
        wait = retry_after + jitter
        print(f"Rate limited. Retry {attempt + 1}/{max_retries} in {wait:.1f}s")
        time.sleep(wait)
        delay = min(delay * 2, 32)
    raise Exception("Max retries exceeded")

Como o CLI trata limites de taxa internamente?

O Nylas CLI trata limites de taxa na camada da plataforma para que você não precise escrever lógica de retry. Quando a API Nylas subjacente recebe um 429 do Gmail, do Graph ou de qualquer provedor conectado, ela tenta de novo com backoff exponencial automaticamente. O CLI herda esse comportamento. Um único comando nylas email list --limit 500 pode disparar dezenas de chamadas de API paginadas nos bastidores, e cada uma respeita os sinais de throttle do provedor sem expor erros a você.

A plataforma processa mais de 1,2 bilhão de chamadas de API por mês entre Gmail, Outlook, Exchange, Yahoo, iCloud e provedores IMAP. Esse volume significa que a lógica de retry já foi testada contra todos os padrões de limite de taxa da tabela acima. O comportamento dos provedores descrito aqui se baseia no comportamento documentado e em nossos testes com Gmail e Outlook; valide localmente antes de fazer deploy de premissas específicas para Yahoo, iCloud ou EWS.

Para ver a resposta bruta da API, incluindo os headers de limite de taxa, adicione --json a qualquer comando. A saída JSON inclui campos de metadados que expõem os headers de resposta do provedor. Isso é útil para depurar scripts que encadeiam vários comandos do CLI, porque você pode inspecionar se um 429 ocorreu e quanto tempo o retry esperou.

# Fetch 500 messages with full JSON output including response metadata
nylas email list --limit 500 --json | jq '.[0:3]'

Para operações em massa, como sincronizar uma caixa de correio inteira ou enviar uma campanha de 2.000 mensagens, o CLI enfileira as requisições internamente e permanece dentro dos limites do provedor. Um sync completo de uma caixa Gmail com 10.000 mensagens leva cerca de 3 minutos na taxa sustentada que a cota permite, contra aproximadamente 40 segundos se fosse possível ignorar os limites.

Quais são os limites de operações em batch por provedor?

Operações em batch permitem agrupar várias chamadas de API em uma única requisição HTTP, reduzindo a sobrecarga de round-trips e, às vezes, contornando throttles por requisição. O Gmail suporta requisições em batch com até 100 chamadas por batch, enquanto o Microsoft Graph limita batches a 20 operações. O Exchange EWS não tem um endpoint formal de batch, mas suporta operações agrupadas via FindItem com paginação.

Segundo a documentação de requisições em batch do Google, cada operação individual dentro de um batch do Gmail ainda custa suas unidades de cota completas. Um batch de 100 chamadas messages.get custa 500 unidades, o mesmo que 100 chamadas individuais. O ganho é latência, não economia de cota. O endpoint $batch da Microsoft é diferente: o batch em si conta como uma única requisição contra o throttle de 10.000/10 min, mas cada operação interna ainda roda de forma independente e pode falhar individualmente.

O CLI usa batching onde o provedor suporta. Para o Gmail, agrupa chamadas messages.get em batches de 100 para reduzir a latência durante a paginação. Para o Graph, empacota até 20 operações por requisição $batch para maximizar a vantagem no throttle. Você não precisa configurar nada; isso acontece automaticamente por trás de nylas email list.

Como monitorar seu uso dos limites de taxa?

O Gmail expõe o uso de cota no Google Cloud Console em APIs & Services > Gmail API > Quotas, onde você vê o consumo de unidades em tempo real, detalhado por método. O Microsoft Graph fornece dados de uso no portal Azure em App Registrations > seu app > Performance. Os dois dashboards atualizam a cada 5 minutos e mostram 30 dias de histórico, o suficiente para identificar padrões nos eventos de throttle.

Para workflows baseados no CLI, adicione --json a qualquer comando e encaminhe a saída para jq para contar resultados e estimar o volume de chamadas de API. O comando abaixo lista 100 mensagens, conta o total e calcula as unidades de cota do Gmail consumidas aproximadamente. A 5 unidades por página de messages.list (100 resultados por página) mais 5 unidades por messages.get de cada mensagem, 100 mensagens custam cerca de 505 unidades de cota.

# Count messages returned and estimate Gmail quota cost
COUNT=$(nylas email list --limit 100 --json | jq 'length')
echo "$COUNT messages fetched"
echo "Estimated quota cost: $((5 + COUNT * 5)) units"

Se você roda scripts de sync periódicos, registre a contagem e o timestamp após cada execução. Um cron job que sincroniza a cada 5 minutos e puxa 200 mensagens por execução consome cerca de 1.005 unidades por ciclo, ou aproximadamente 289.440 unidades por dia. Isso fica bem abaixo do limite diário de 1 bilhão de unidades por projeto, mas vale acompanhar se você escalar para milhares de usuários.

Próximos passos

• Consulte a referência completa de comandos para ver todos os comandos de e-mail, calendário e contatos
• Paginação e sync da Gmail API explicados para uma análise detalhada de nextPageToken e historyId
• Enviar e-mail pelo terminal para começar rápido com nylas email send
• Melhor infraestrutura de e-mail para agentes de IA para comparar plataformas de API para workflows de e-mail automatizados