Paginação e sincronização da API do Gmail

Como funcionam nextPageToken e maxResults na API do Gmail?

O parâmetro maxResults da API do Gmail controla quantos IDs de mensagem users.messages.list retorna em uma página, até o máximo de 500. Quando existem mais mensagens correspondentes, a resposta inclui nextPageToken. Passe esse token de volta como pageToken na próxima requisição até que a resposta deixe de incluir outro token.

Para a busca comum gmail api nextPageToken maxResults, a regra principal é que maxResults é apenas o tamanho da página, não o limite total de resultados. Uma caixa de correio com 10.000 mensagens correspondentes ainda precisa de requisições repetidas, persistência de tokens, tratamento de retry e uma segunda chamada messages.get para o corpo de cada mensagem.

Como funciona a paginação da API do Gmail

A paginação da API do Gmail divide conjuntos grandes de resultados em várias respostas HTTP, cada uma contendo um nextPageToken que o cliente deve passar de volta para recuperar o próximo lote. O endpoint messages.list retorna no máximo 500 resultados por requisição, então uma caixa de entrada com 10.000 mensagens exige pelo menos 20 chamadas sequenciais à API para ser percorrida por completo.

Segundo a documentação do messages.list da API do Gmail, cada chamada custa 5 unidades de cota, e o tamanho de página padrão é 100 (configurável até 500 com maxResults). Toda requisição exige um token de acesso OAuth2 válido. O loop abaixo demonstra esse padrão em Python — ele chama messages.list repetidamente, coleta os IDs de mensagem e encerra quando nextPageToken não está presente:

from googleapiclient.discovery import build

service = build("gmail", "v1", credentials=creds)

all_messages = []
page_token = None

while True:
    response = service.users().messages().list(
        userId="me",
        maxResults=500,
        pageToken=page_token,
    ).execute()

    all_messages.extend(response.get("messages", []))
    page_token = response.get("nextPageToken")

    if not page_token:
        break

print(f"Fetched {len(all_messages)} message IDs")

São 18 linhas só para coletar IDs de mensagem. Você ainda precisa chamar messages.get em cada um para buscar assuntos, remetentes e corpos — cada chamada custa mais 20 unidades de cota na tabela de cotas atual do Gmail.

Como funciona a sincronização incremental do Gmail

A sincronização incremental do Gmail rastreia mudanças na caixa de correio por meio de um historyId monotonicamente crescente, então você busca apenas o que mudou desde a última sincronização. Repaginar por completo uma caixa de entrada de 10.000 mensagens custa pelo menos 100 unidades de cota só em chamadas messages.list, então o endpoint history.list existe para evitar esse custo, retornando apenas mensagens novas, excluídas ou com marcadores alterados.

Você armazena o historyId da última sincronização. Na execução seguinte, chama history.list com startHistoryId para obter apenas as mudanças desde então. O guia de sincronização do Gmail recomenda essa como a abordagem principal para manter uma cópia local sincronizada. O parâmetro historyTypes permite filtrar por tipo de mudança: messageAdded, messageDeleted, labelAdded e labelRemoved. Cada chamada history.list custa 2 unidades de cota — 60% mais barata que uma chamada messages.list a 5 unidades. A função Python abaixo percorre os registros de histórico paginados, coletando as mudanças e retornando o historyId mais recente para a próxima sincronização:

def get_changes_since(service, start_history_id):
    """Fetch all mailbox changes since the given historyId."""
    changes = []
    page_token = None

    while True:
        response = service.users().history().list(
            userId="me",
            startHistoryId=start_history_id,
            historyTypes=["messageAdded", "messageDeleted"],
            pageToken=page_token,
        ).execute()

        changes.extend(response.get("history", []))
        page_token = response.get("nextPageToken")

        if not page_token:
            break

    new_history_id = response.get("historyId")
    return changes, new_history_id

Há um porém: history IDs expiram após cerca de 30 dias. Se o historyId armazenado for antigo demais, history.list retorna 404 Not Found (ou às vezes 410 Gone), e você precisa recorrer a uma sincronização completa. Seu código precisa tratar os dois caminhos.

Os problemas de fazer tudo por conta própria

Construir um cliente de sincronização do Gmail pronto para produção significa lidar com o ciclo de vida de tokens OAuth2, fallback de histórico expirado, limites de taxa e falhas parciais — tudo em código que você mesmo mantém. O que começa como um loop de paginação de 20 linhas cresce para 80-120 linhas quando você adiciona callbacks de renovação de token, backoff exponencial para respostas 429 e caminhos de código duplos para sincronização delta vs. completa. Os casos extremos se acumulam:

• Gerenciamento de tokens OAuth2 — Tokens de acesso do Gmail expiram a cada 3.600 segundos. Seu loop de sincronização precisa detectar tokens expirados, renová-los usando o refresh token e repetir a requisição que falhou. Isso significa um callback de renovação de token, tratamento de erros e lógica de retry.
• Fallback de historyId expirado — Quando history.list retorna 404, você precisa abandonar a sincronização delta e executar uma sincronização completa por paginação. Dois caminhos de código, e os dois precisam funcionar corretamente.
• Limites de taxa — Projetos novos da API do Gmail recebem 6.000 unidades de cota por minuto por usuário por projeto. Uma chamada messages.list custa 5 unidades, um messages.get custa 20 unidades e um history.list custa 2 unidades. Se você está sincronizando uma caixa de correio grande, precisa de throttling do lado do cliente e backoff exponencial em respostas 429 Too Many Requests.
• Falhas parciais de página — Um erro de rede no meio da paginação significa que você tem metade dos resultados. Você repete desde o início ou a partir do último token de página? É preciso rastrear estado.
• Custo de configuração da API do Gmail — Antes de escrever qualquer código que chame a API do Gmail, você precisa de um projeto no Google Cloud, uma tela de consentimento OAuth, um client ID e secret, e um redirect URI configurado em console.cloud.google.com. São 15-20 minutos clicando em formulários web.

Um loop de sincronização confiável cobrindo as cinco preocupações chega a 80-120 linhas de Python antes de você adicionar logging, persistência ou suporte a múltiplas contas.

Guias relacionados de paginação de API e fluxos de e-mail

A paginação do Gmail costuma estar ao lado de trabalhos de integração adjacentes: sincronização de eventos de calendário, listagem de caixa de entrada neutra em relação ao provedor, entrega de webhooks, planejamento de cotas de API e acesso a e-mail seguro para agentes. Use este mapa quando precisar de um caminho de implementação mais específico.

Listar e-mails do Gmail com um comando

O Nylas CLI substitui toda a pilha de paginação e sincronização por um único comando de terminal que cuida internamente da renovação de tokens OAuth2, dos limites de taxa e da busca em múltiplas páginas. Onde a abordagem da API do Gmail exige 80-120 linhas de Python e 15-20 minutos de configuração da API no Google Cloud, o CLI reduz isso a uma linha e uma instalação de 2 minutos.

Os três comandos a seguir mostram padrões comuns: listar mensagens recentes, filtrar por assunto e filtrar por remetente. Cada um executa uma única chamada de API por baixo dos panos enquanto o CLI gerencia a paginação entre as respostas do provedor:

# List the 50 most recent emails
nylas email list --limit 50 --json

# Filter by subject
nylas email search "invoice" --json

# Filter by sender
nylas email list --from "boss@company.com" --json

O CLI pagina pela API do Gmail nos bastidores, renova tokens OAuth2 expirados automaticamente e retorna os resultados como JSON. Nenhum projeto da API do Gmail para registrar, nenhuma tela de consentimento, nenhum redirect URI. Começando agora? O guia de primeiros passos cobre a instalação e a primeira autenticação.

Buscar e filtrar

O Nylas CLI suporta busca em texto completo e filtros por campo que mapeiam para o mesmo parâmetro q do Gmail usado por messages.list, mas sem o loop de paginação nem o encanamento de OAuth2. A API do Gmail exige pelo menos 3 chamadas sequenciais para buscar, paginar e obter os corpos das mensagens — o CLI condensa isso em um único comando.

Os três exemplos abaixo cobrem os padrões de busca mais comuns: busca por palavra-chave, filtro de não lidos e filtro por intervalo de datas. Os filtros de data ficam em nylas email search como --after e --before, que recebem datas YYYY-MM-DD e aceitam "*" como consulta que corresponde a tudo. Cada exemplo retorna o JSON completo das mensagens, incluindo assuntos, remetentes e corpos:

# Full-text search
nylas email search "quarterly report" --json

# Unread emails only
nylas email list --unread --json

# Emails received in the last 7 days
nylas email search "*" --after 2026-06-02 --json

O equivalente na API do Gmail exige construir a string de consulta, passá-la a messages.list, paginar os resultados com nextPageToken e chamar messages.get em cada um dos IDs retornados para obter assuntos e corpos. São 4 etapas e pelo menos 10 unidades de cota por página.

Ler o conteúdo das mensagens, não só os IDs

O endpoint messages.list da API do Gmail retorna apenas IDs de mensagem — nunca assuntos, remetentes ou corpos. Para ler o conteúdo de verdade, você chama messages.get em cada ID coletado, e cada chamada custa mais 20 unidades de cota. Depois de paginar 10.000 mensagens, você faz mais 10.000 chamadas de API totalizando 200.000 unidades de cota, o que consome mais de 33 minutos de cota por usuário sob o limite de projeto por usuário de 2026.

O CLI condensa as duas etapas em um comando. nylas email read <id> busca uma única mensagem com o corpo completo em uma chamada. nylas email search executa uma consulta do lado do servidor e retorna as mensagens correspondentes com seu conteúdo na mesma resposta. Ambos suportam três modos de saída pela flag global --format — table, json e yaml — com --json como atalho para o modo JSON. Para a fonte RFC822 bruta que messages.get retorna com format=raw, passe --mime a nylas email read. A saída JSON encaixa direto no jq para processamento posterior no shell.

# Read a single message
nylas email read 18b9a3f2cd47e102 --json

# Search and return full bodies in one round-trip
nylas email search "urgent" --from boss@example.com --json

Paginar threads em vez de mensagens

O Gmail organiza mensagens em threads de conversa, e o endpoint threads.list é um recurso paginado separado de messages.list. Uma caixa de entrada de 10.000 mensagens normalmente se resolve em 2.000-4.000 threads dependendo da densidade das conversas, então listar threads reduz o total de páginas em 60-80%. Cada resposta de thread carrega o mesmo contrato de nextPageToken de messages.list, além de um array threads[].messages[] contendo todas as mensagens da conversa.

A superfície de threads no CLI espelha a superfície de mensagens com cinco comandos. nylas email threads list pagina pelas threads. nylas email threads show busca uma única thread por ID. nylas email threads search recebe uma string de consulta no estilo do Gmail. nylas email threads mark altera o estado de leitura de todas as mensagens da thread de uma vez. nylas email threads delete exclui a conversa inteira.

# Paginate threads in pages of 50
nylas email threads list --limit 50 --json

# Mark a whole conversation as read in one command
nylas email threads mark <thread-id> --read

Paginar dentro de um marcador ou pasta específica

O Gmail organiza mensagens por marcadores — marcadores de sistema como INBOX, SENT, STARRED, UNREAD, SPAM e TRASH, além de marcadores criados pelo usuário. Microsoft Graph e provedores IMAP usam pastas. O endpoint messages.list do Gmail aceita um array labelIds para marcadores de sistema ou o parâmetro q com uma sintaxe de busca como label:Receipts para marcadores personalizados. Os tokens de paginação carregam o escopo do filtro, então um arquivo de 50.000 mensagens limitado a um marcador retorna proporcionalmente menos páginas.

nylas email search aceita --in para limitar uma consulta a um marcador ou pasta — passe "*" como consulta para corresponder a todas as mensagens dentro dele. nylas email folders list retorna todos os marcadores ou pastas da conta conectada, então a mesma flag funciona com marcadores do Gmail, pastas do Outlook e nomes de pastas IMAP sem mudar a sintaxe. A superfície de flags do comando de busca também inclui --unread, --starred e --has-attachment.

# List every label or folder on the connected account
nylas email folders list --json

# Paginate only inside the Receipts label
nylas email search "*" --in Receipts --limit 100 --json

# Combine label scope with a query
nylas email search "stripe" --in Receipts --json

Paginar entre várias contas

Clientes de sincronização em produção costumam lidar com várias caixas conectadas — uma equipe de sales-ops agregando quatro caixas compartilhadas, um agente de IA operando em cinco contas de usuário, um CRM extraindo sinais de e-mail de todas as contas de um workspace. A API do Gmail aplica cota por grant OAuth, então sincronizar 10 contas em paralelo funciona sem throttling entre contas, mas o código da aplicação precisa gerenciar 10 refresh tokens separados, 10 timers de expiração de token e 10 checkpoints de historyId.

Grants são entidades de primeira classe no CLI. nylas auth list mostra todas as contas conectadas. nylas auth whoami imprime qual grant o próximo comando usará. nylas auth switch troca o grant ativo. Comandos de e-mail e calendário também aceitam um ID de grant como argumento posicional opcional, então um único shell script pode iterar pelos grants sem alterar o estado ativo.

# Show every connected grant as JSON
nylas auth list --json

# Run the same sync across every Google grant
for grant in $(nylas auth list --json | jq -r '.[] | select(.provider == "google") | .id'); do
  nylas email search "*" "$grant" --after 2026-05-01 --json
done

Sincronizar em CI, cron jobs e ambientes headless

O pop-up de OAuth2 no navegador da API do Gmail é um bloqueio total em CI, contêineres Docker, sandboxes de agentes de IA e qualquer ambiente sem supervisão. O fluxo de acesso offline do Google exige que a aplicação capture um refresh token durante uma configuração interativa única, depois o armazene em um gerenciador de segredos e o renove programaticamente. A alternativa recomendada (uma service account com Domain-Wide Delegation) é restrita a administradores do Google Workspace e exige uma mudança de configuração no nível do workspace.

O Nylas CLI contorna o navegador por completo com autenticação por chave de API. nylas auth config --api-key armazena uma chave localmente sem tocar em um navegador. nylas auth token gera um bearer token com escopo para chamadas de API subsequentes. nylas auth status informa o estado atual de autenticação — útil para health checks em deploys conteinerizados.

# In a GitHub Action or cron job — no browser needed
export NYLAS_API_KEY="nyk_..."
nylas auth config --api-key "$NYLAS_API_KEY"
nylas email search "*" --after $(date -u -v-1d +%Y-%m-%d) --json > /var/log/digest.json

Em Manus, Replit e sandboxes de agentes de IA semelhantes que não têm navegador, o mesmo fluxo se aplica — o agente provisiona uma chave uma vez, a persiste no ambiente e todos os comandos seguintes rodam sem etapas interativas.

Webhooks em vez de polling

Fazer polling de uma caixa do Gmail a cada 5 minutos gera 288 chamadas de API por dia por caixa. Em 1.000 usuários conectados, são 288.000 chamadas diárias, e a maioria retorna zero mensagens novas. O Gmail oferece uma alternativa de notificações push via Cloud Pub/Sub: você cria um tópico Pub/Sub, concede a gmail-api-push@system.gserviceaccount.com o papel pubsub.publisher, chama users.watch em cada caixa e renova o watch a cada 7 dias porque o Google o expira. O custo de configuração é alto, e uma renovação esquecida quebra a sincronização silenciosamente.

Webhooks no CLI funcionam sem um tópico Pub/Sub. nylas webhook create registra um endpoint HTTPS e uma lista de gatilhos. nylas webhook list mostra o que está registrado. nylas webhook triggers imprime todos os tipos de evento suportados (message.created, message.updated, thread.replied, além de eventos de calendário e contatos). nylas webhook test send dispara um payload de exemplo contra seu endpoint para você validar o receptor antes de entrar em produção. nylas webhook verify valida a assinatura HMAC dos payloads recebidos.

# Register a webhook for new message events
nylas webhook create \
  --url https://example.com/hooks/nylas \
  --triggers message.created \
  --json

# Verify a payload from your receiver
nylas webhook verify \
  --payload-file ./incoming.json \
  --signature "$X_NYLAS_SIGNATURE" \
  --secret "$WEBHOOK_SECRET"

Webhooks disparam em eventos reais, normalmente menos de 100 por caixa por dia para um usuário médio. Uma carga de polling de 288.000 chamadas por dia encolhe para cerca de 100.000 eventos por dia nas mesmas 1.000 caixas, e a latência entre uma mensagem nova chegar e a aplicação enxergá-la cai de até 5 minutos para cerca de 1 segundo.

Como outros provedores de e-mail lidam com paginação

O Gmail não é o único provedor com um contrato de paginação que vale a pena entender. O Microsoft Graph (Outlook e Exchange Online) usa @odata.nextLink — uma URL completa que o cliente segue ao pé da letra. O IMAP (Yahoo Mail, iCloud Mail, IMAP hospedado) não pagina no sentido tradicional: UID SEARCH retorna todos os UIDs correspondentes em uma única resposta, o que pode ser lento em caixas grandes, mas elimina a lógica de cursor do lado do cliente. O Exchange Web Services (EWS, usado por implantações mais antigas do Exchange) usa paginação indexada com IndexedPageItemView e um offset BasePoint.

Guias por provedor percorrem o mesmo problema de paginação em cada contrato: Listar e-mails do Outlook pela linha de comando, Listar e-mails do Exchange, Listar e-mails do Yahoo, Listar e-mails do iCloud e Listar e-mails IMAP. O mesmo comando nylas email list está documentado para rodar em todos os provedores com flags idênticas.

O comportamento do lado do provedor para Outlook, Exchange, Yahoo, iCloud e IMAP descrito acima vem da documentação pública de cada provedor, não de uma execução verificada de ponta a ponta em cada backend. Teste localmente antes de implantar fluxos específicos de provedor.

Quanto tempo leva para sincronizar uma caixa do Gmail?

Benchmarks sintéticos contra uma caixa de testes, executados em uma conexão de banda larga residencial (~150 ms de latência mediana até os servidores do Google), mostram a diferença de custo entre a paginação manual e um único comando do CLI. A coluna do loop em Python inclui chamadas messages.list + messages.get com backoff exponencial em respostas 429. Os números do CLI incluem as mesmas chamadas internas, agrupadas e paralelizadas.

O custo de cota é fixado pelo preço por chamada do Gmail, não pelo cliente. O CLI não consegue tornar uma chamada messages.list mais barata, mas consegue manter a paginação e o comportamento de retry fora do código da sua aplicação. Um loop Python ingênuo que busca 10.000 corpos completos gasta cerca de 200.000 unidades de cota só em chamadas messages.get. Acompanhar esses números importa ao planejar uma sincronização completa do zero; veja nylas email list para as flags que controlam batching e concorrência.

Receitas comuns

Quatro padrões de shell que combinam paginação de e-mail com ferramentas UNIX padrão. Cada um usa jq para interpretar a saída JSON e --json para formatação legível por máquina.

Contar todos os e-mails não lidos

Encadeie nylas email list --unread --json com jq 'length' para obter um único número. Útil para dashboards automatizados ou alertas de plantão. Combine com watch -n 60 para um contador ao vivo que atualiza uma vez por minuto. A saída JSON é paginada automaticamente — você não precisa tratar nextPageToken no wrapper.

nylas email list --unread --json | jq 'length'

Cron job de resumo diário

Um script de resumo que roda uma vez por dia via cron usa nylas email search com --after fixado na data de ontem, despeja o JSON em um arquivo temporário e encadeia um resumo de uma linha por mensagem no mail. Substitua nylas auth login por nylas auth config --api-key na máquina que roda o cron para não precisar de navegador.

# /etc/cron.daily/email-digest.sh
yesterday=$(date -u -v-1d +%Y-%m-%d)
nylas email search "*" --after "$yesterday" --json > /tmp/digest.json
jq -r '.[] | "\(.from) - \(.subject)"' /tmp/digest.json \
  | mail -s "Daily digest" you@example.com

Encontrar todos os e-mails com anexo de um remetente específico

Encadeie nylas email search com nylas email attachments list para encontrar todos os anexos de um remetente em um único pipeline. email search aplica os filtros --from e --has-attachment do lado do servidor, e então attachments list enumera cada resultado. Encadeie com nylas email attachments download quando quiser os arquivos no disco.

nylas email search "*" --from billing@stripe.com --has-attachment --json \
  | jq -r '.[].id' \
  | xargs -I{} nylas email attachments list {} --json

Extrair códigos OTP de e-mails de login recentes automaticamente

Busque todos os e-mails relacionados a login recebidos desde ontem, extraia qualquer número de 6 dígitos do corpo e imprima a primeira correspondência. A palavra-chave verification captura o assunto transacional mais comum; rode de novo com OTP ou code para cobrir outros remetentes. Sozinho, esse é o fundamento do guia dedicado de extração de OTP. Para análises de caixa de entrada que vão além de contagens simples, veja nylas email ai analyze. Usuários de PowerShell podem adaptar esses padrões em relatórios de e-mail no PowerShell.

nylas email search "verification" \
  --after "$(date -u -v-1d +%Y-%m-%d)" \
  --json \
  | jq -r '.[].body' \
  | grep -oE '[0-9]{6}' \
  | head -1

Comparação lado a lado

A tabela abaixo compara a abordagem em Python da API do Gmail com o Nylas CLI em 9 capacidades que importam em produção. A maior diferença é o tempo de configuração: o caminho da API do Gmail exige 15-20 minutos de configuração no console mais 80-120 linhas de código, enquanto o CLI leva cerca de 2 minutos para instalar e autenticar.

Perguntas frequentes

O que é nextPageToken na API do Gmail?

Quando você chama messages.list, a API do Gmail retorna até 500 resultados por página. Se existirem mais mensagens, a resposta inclui uma string nextPageToken. Você passa esse token como o parâmetro pageToken na próxima requisição para buscar a página seguinte. O loop continua até que a resposta não contenha mais um nextPageToken, o que significa que você chegou ao fim.

Como funciona a sincronização incremental do Gmail com historyId?

Cada mudança em uma caixa do Gmail (mensagens novas, exclusões, alterações de marcadores) recebe um historyId monotonicamente crescente. Você armazena o historyId da última sincronização e depois chama history.list com startHistoryId para obter apenas as mudanças desde então. History IDs expiram após cerca de 30 dias. Se o ID armazenado for antigo demais, a API retorna 404 e você precisa de um fallback de sincronização completa.

Posso listar e-mails do Gmail sem configurar a API do Gmail?

Sim. O Nylas CLI cuida do OAuth2 e da autenticação com o provedor internamente. Execute nylas email list --limit 50 --json para listar sua caixa do Gmail sem registrar um cliente da API do Gmail no Google Cloud, configurar uma tela de consentimento OAuth ou gerenciar tokens de acesso. O CLI funciona da mesma forma em seis provedores.

O CLI trata os limites de taxa da API do Gmail?

Sim. A API do Gmail dá a projetos novos 6.000 unidades de cota por minuto por usuário por projeto, e uma chamada messages.list custa 5 unidades. O CLI gerencia limites de taxa, paginação, renovação de token e lógica de retry internamente. Você recebe os resultados sem escrever nenhum código de rastreamento de cota ou de backoff.

Posso paginar threads do Gmail em vez de mensagens?

Sim. nylas email threads list pagina o endpoint threads.list em vez de messages.list. Uma caixa típica tem cerca de 1 thread para cada 3-4 mensagens, então o número de páginas é 60-80% menor. Combine com nylas email threads mark para marcar todas as mensagens de uma conversa como lidas em um único comando.

Como listo e-mails apenas de um marcador específico do Gmail?

Passe o nome do marcador para --in em nylas email search. O comando nylas email search "*" --in Receipts --json retorna apenas mensagens com o marcador Receipts. Use nylas email folders list para ver todos os marcadores ou pastas da conta. A mesma flag funciona para pastas do Outlook, pastas IMAP do Yahoo e pastas do iCloud sem mudar a sintaxe.

Posso sincronizar o Gmail em um cron job sem pop-up de OAuth?

Sim. Use nylas auth config --api-key em vez de nylas auth login. O fluxo por chave de API não abre navegador, então roda em máquinas headless, contêineres Docker, pipelines de CI e sandboxes de agentes de IA como o Manus. Armazene a chave como segredo no ambiente que executa o cron job.

Como sincronizo apenas as últimas 24 horas de e-mail?

Passe --after a nylas email search. Para as últimas 24 horas: nylas email search "*" --after $(date -u -v-1d +%Y-%m-%d) --json. A flag recebe uma data YYYY-MM-DD, e o CLI a traduz para a sintaxe de filtro que o provedor subjacente usa — para o Gmail, isso vira uma consulta q=after: contra a API.

O CLI funciona com Outlook, Yahoo e iCloud da mesma forma?

Sim. Os mesmos comandos nylas email list, nylas email search e nylas email read funcionam com Gmail, Outlook, Exchange, Yahoo, iCloud e IMAP. A ferramenta traduz cada comando para a chamada de API específica do provedor: a API REST do Gmail, o Microsoft Graph, o UID SEARCH do IMAP ou o EWS. Os passo a passo por provedor estão em Listar e-mails do Outlook, Listar e-mails IMAP e Listar e-mails do Exchange.

O que acontece se meu historyId tiver mais de 30 dias?

O Gmail retorna um 404 em history.list e você precisa recorrer a uma sincronização completa por paginação. O CLI trata esse fallback automaticamente — você não vê o 404 e não precisa escrever dois caminhos de código. O controle de concorrência baseado em ETag e o tratamento de If-Match são cobertos em Tratamento de If-Match e ETag na API do Gmail.

Posso receber notificações push em vez de fazer polling?

Sim. nylas webhook create registra um endpoint HTTPS para eventos como message.created e thread.replied sem exigir um tópico Cloud Pub/Sub nem um administrador do Google Workspace. Execute nylas webhook triggers para ver todos os tipos de evento suportados.

Próximos passos

A paginação do Gmail e a sincronização incremental são dois dos desafios de integração de API mais comuns, mas não são os únicos. Estes guias relacionados cobrem fluxos adjacentes, incluindo envio de e-mail, controle de concorrência baseado em ETag e a superfície completa de comandos do CLI.

• Listar e-mails do Gmail pela linha de comando — filtre por remetente, assunto, data e estado de leitura
• Enviar Gmail pela linha de comando — envio específico do Gmail sem código cliente da API do Gmail nem configuração SMTP
• Exemplos de consultas de busca da API do Gmail — q, marcadores, categorias, anexos e equivalentes no CLI
• Sincronização incremental da API do Gmail com historyId e ETags — aprofundamento em ETags, If-Match e tratamento de 412
• Cotas da API do Gmail em 2026 — unidades de cota atuais, custos por método, limite de cobrança e padrões seguros para agentes
• Por que a API do Gmail quebra agentes de IA — prompts de OAuth, estado de paginação, parsing de MIME e pressão de cota
• APIs de e-mail para agentes de IA comparadas — trade-offs entre Gmail, Microsoft Graph, IMAP e APIs neutras em relação ao provedor
• Paginação e sincronização da API do Google Calendar — os mesmos padrões aplicados a events.list e syncToken
• Testar webhooks de e-mail localmente — valide a sincronização orientada a eventos antes de substituir loops de polling
• Listar e-mails do Outlook pela linha de comando — paginação do Microsoft Graph com @odata.nextLink
• Listar e-mails IMAP pela linha de comando — Yahoo, iCloud e IMAP hospedado via UID SEARCH
• Enviar e-mail pelo terminal — fluxos de envio em bash, zsh e multiplataforma
• Extrair códigos OTP de e-mails — automatize a captura de códigos de verificação em scripts
• Relatórios de e-mail no PowerShell — os mesmos padrões de paginação adaptados para shells do Windows
• Primeiros passos — métodos de instalação (Homebrew, shell script, PowerShell, Go) e primeira autenticação
• Referência completa de comandos — todas as flags e subcomandos documentados