Guide

Exemplos de consulta de busca da Gmail API

Exemplos de consulta de busca da Gmail API para o parâmetro q, labels, categorias, datas, anexos e rfc822msgid. Veja a sintaxe direta da API e traduza os casos comuns para filtros suportados pelo CLI.

Written by Qasim Muhammad Staff SRE

Reviewed by Nick Barraclough

Verified — CLI 3.1.11 · last tested May 16, 2026

Como funciona a sintaxe de consulta de busca da Gmail API?

A sintaxe de consulta de busca da Gmail API funciona passando uma expressão de busca do Gmail no parâmetro de query q de users.messages.list. O Google documenta que o parâmetro suporta o mesmo formato de consulta da caixa de busca do Gmail, então uma única requisição HTTP pode filtrar por remetente, destinatário, assunto, estado não lido, data, presença de anexo e ID de mensagem.

A limitação principal é que messages.list retorna IDs de mensagem, não corpos completos. O método retorna 100 resultados por padrão e aceita até 500 resultados por página, então uma busca que retorna 1.500 correspondências ainda precisa de pelo menos 3 chamadas de listagem antes de você buscar qualquer conteúdo. A referência oficial de users.messages.list também observa que q não pode ser usado com o escopo gmail.metadata.

Este exemplo mínimo em Python mostra o formato direto da API. Ele busca e-mails não lidos de um remetente, limita a primeira página a 50 IDs e deixa a leitura dos corpos das mensagens para uma segunda etapa. Essa separação importa porque cada leitura de corpo é mais uma chamada de API.

response = service.users().messages().list(
    userId="me",
    q="from:billing@stripe.com is:unread",
    maxResults=50,
).execute()

message_ids = [message["id"] for message in response.get("messages", [])]

Como buscar por remetente, destinatário, assunto e estado não lido?

As consultas de busca do Gmail combinam operadores de campo em uma única string, então filtros de remetente, destinatário, assunto e não lido podem viver no mesmo valor de q. O padrão prático é manter a consulta restrita antes de a paginação começar, porque cada resultado extra pode virar mais uma chamada de messages.get depois.

Os exemplos do Google incluem operadores como from:, rfc822msgid: e is:unread. A interface do Gmail também suporta to:, subject:, frases exatas e negação. No código da API, os operadores são só uma string codificada para URL; o servidor faz a busca e retorna os IDs das mensagens correspondentes. Um limite de 25 resultados é uma boa primeira passada para jobs de agente ou cron, porque entrega candidatos suficientes sem forçar a leitura da caixa inteira.

Este comando do CLI usa flags verificadas de nylas email search. A query posicional é invoice porque o comando atual trata uma query sem curinga como texto de assunto; operadores de campo como from: são sintaxe da Gmail API, não pass-through bruto do CLI. O comando retorna 25 resultados em JSON para scripts ou ferramentas de agente.

nylas email search "invoice" \
  --from "billing@stripe.com" \
  --unread \
  --limit 25 \
  --json

Como funcionam as buscas por labels e categorias do Gmail?

Labels do Gmail não são pastas; são tags que podem aparecer em muitas mensagens, e uma mensagem pode carregar várias labels ao mesmo tempo. O Google documenta 2 famílias de labels: labels SYSTEM reservadas, como INBOX, e labels USER personalizadas, criadas pelo dono da caixa ou por uma integração.

O guia de labels do Gmail lista labels de sistema comuns, incluindo INBOX, SPAM, TRASH, UNREAD, STARRED e 5 labels de categoria, como CATEGORY_PERSONAL, CATEGORY_SOCIAL, CATEGORY_PROMOTIONS, CATEGORY_UPDATES e CATEGORY_FORUMS. As consultas de busca costumam usar a sintaxe voltada ao usuário, como category:promotions, enquanto os filtros de label da API usam IDs de label, como CATEGORY_PROMOTIONS.

O CLI expõe as labels de categoria do Gmail pela mesma interface no estilo de pastas usada para os outros provedores. Este exemplo busca 25 mensagens de Promoções e depois roda uma busca por assunto nas mensagens da aba Social. Os dois comandos usam --in, que é o filtro de pasta verificado de nylas email search.

nylas email search "*" --in "CATEGORY_PROMOTIONS" --limit 25 --json

nylas email search "webinar" \
  --in "CATEGORY_SOCIAL" \
  --limit 25 \
  --json

Como buscar anexos sem decodificar MIME antes?

Buscas de anexos no Gmail devem começar pelo índice de busca, não pelo parsing de MIME. A consulta has:attachment restringe o conjunto de resultados antes de o seu código baixar os payloads das mensagens, o que evita decodificar todas as mensagens de uma caixa grande só para descobrir que apenas 3 contêm arquivos.

O download do anexo ainda é uma segunda etapa de API. O recurso de anexos do Gmail descreve o attachmentId como o valor usado em uma requisição separada de messages.attachments.get, e os dados retornados vêm codificados em base64url. Isso significa que uma integração direta com o Gmail precisa de busca, travessia das partes da mensagem, lookup do ID do anexo, decodificação de bytes e escrita do arquivo.

O CLI mantém a primeira passada pequena e adia o download do arquivo até você selecionar uma mensagem e um ID de anexo. Estes 3 comandos buscam mensagens com anexo, listam os anexos de uma mensagem selecionada e baixam um anexo específico para um caminho local.

nylas email search "*" --has-attachment --from "billing@stripe.com" --limit 25 --json

nylas email attachments list <message-id> --json

nylas email attachments download <attachment-id> <message-id> --output ./invoice.pdf

Como buscar intervalos de datas e e-mails antigos?

As buscas por data no Gmail usam operadores como after:, before:, older: e newer: dentro da expressão de busca, enquanto o CLI expõe os limites de data como flags explícitas. As duas abordagens devem usar datas fixas em automações, para que o mesmo job produza resultados repetíveis em reexecuções de 24 horas.

Janelas fixas evitam varreduras escondidas da caixa de correio. Um job mensal de faturas pode buscar só janeiro de 2026 e depois ler mensagens selecionadas após ranquear assunto e remetente. No código da API, esse intervalo de datas fica dentro da string q. No CLI, --after e --before deixam os limites de data visíveis para um revisor e fáceis de impor em um wrapper.

Este comando busca mensagens com fatura no assunto entre 1º de janeiro e 1º de fevereiro de 2026. Ele retorna no máximo 50 candidatos, o suficiente para um relatório humano ou uma etapa de ranqueamento de agente sem deixar a recuperação se expandir para milhares de corpos.

nylas email search "invoice" \
  --after 2026-01-01 \
  --before 2026-02-01 \
  --limit 50 \
  --json

Como encontrar uma mensagem com rfc822msgid?

O operador rfc822msgid: busca um ID de mensagem da Internet específico, o que é útil quando um webhook, bounce, linha de log ou ticket de suporte registra o header Message-ID original. Em vez de varrer por assunto, a busca mira um identificador globalmente significativo que normalmente mapeia para 1 conversa.

O Google inclui rfc822msgid: nos exemplos da documentação de users.messages.list. O operador é mais útil para depurar envios duplicados, fan-out de webhooks e encadeamento de respostas, porque dispensa a busca textual difusa. O resultado ainda pode incluir mais de 1 mensagem se existirem cópias entre labels ou visões de thread, então mantenha um limite baixo e inspecione os IDs antes de ler os corpos.

O CLI não expõe hoje um pass-through bruto do q do Gmail para rfc822msgid:. Use a Gmail API diretamente para esse operador exato e use as flags do CLI somente quando puder aproximar a busca com filtros de remetente, assunto, data, pasta ou anexo. Este exemplo limita o conjunto de resultados da API a 5 IDs.

response = service.users().messages().list(
    userId="me",
    q="rfc822msgid:<20260516.12345@example.com>",
    maxResults=5,
).execute()

message_ids = [message["id"] for message in response.get("messages", [])]

Como paginar resultados de busca do Gmail com segurança?

Uma paginação segura de busca no Gmail mantém a consulta estável, armazena o nextPageToken atual e para assim que o limite de negócio é atingido. A API permite até 500 resultados por página, mas jobs de produção normalmente devem definir um teto total menor, como 200 ou 1.000 mensagens.

A paginação é onde o código direto de API cresce rápido. Você precisa de um loop para o nextPageToken, um teto de resultados, comportamento de retry para falhas transitórias e uma forma de retomar sem reprocessar a mesma página duas vezes. Se um job diário só precisa dos 200 recibos mais novos, buscar 2.000 correspondências aumenta o custo de cota e o tempo de revisão sem melhorar o resultado.

Este loop em Python mantém a consulta de busca constante e para após 200 IDs de mensagem. Ele demonstra o estado extra que uma integração direta carrega antes mesmo de poder chamar messages.get para assuntos, snippets ou corpos.

query = "from:billing@stripe.com has:attachment after:2026/01/01"
page_token = None
message_ids = []

while len(message_ids) < 200:
    response = service.users().messages().list(
        userId="me",
        q=query,
        maxResults=min(100, 200 - len(message_ids)),
        pageToken=page_token,
    ).execute()

    message_ids.extend(message["id"] for message in response.get("messages", []))
    page_token = response.get("nextPageToken")

    if not page_token:
        break

Como transformar resultados de busca do Gmail em mensagens legíveis?

Os resultados de busca do Gmail só se tornam legíveis depois de uma segunda etapa de fetch, porque messages.list retorna registros leves de mensagem. Para mostrar assunto, remetente, snippet ou corpo, o código precisa chamar messages.get para os IDs selecionados e depois interpretar os headers e o payload codificado em base64url.

Essa é a parte que muitos exemplos escondem. Uma busca que retorna 50 IDs de mensagem pode virar 50 chamadas de acompanhamento se o seu workflow ler todas as correspondências. Para workflows de agente, um padrão mais seguro é buscar primeiro, ranquear os metadados, ler de 1 a 5 mensagens selecionadas e parar. O CLI espelha essa fronteira de recuperação com os comandos separados nylas email search e nylas email read.

Estes comandos buscam primeiro e leem uma mensagem escolhida em seguida. Esse formato em 2 etapas é intencional: permite que um script ou modelo inspecione IDs e snippets antes de gastar mais chamadas com o conteúdo dos corpos.

nylas email search "contract" --from legal@example.com --limit 10 --json

nylas email read <message-id> --json

Como o CLI mapeia a busca entre provedores?

O CLI dá aos desenvolvedores um único comando de busca, enquanto 6 famílias de provedores mantêm seus próprios mecanismos de busca e modelos de caixa de correio. O Gmail tem o q e as labels, o e-mail da Microsoft tem a filtragem do Graph e APIs de pastas, e os servidores IMAP expõem SEARCH mais pastas de caixa. O contrato útil é uma única superfície de comando com o comportamento específico de cada provedor escondido por trás dela.

O comportamento dos provedores descrito neste guia vem da documentação do Google e da ajuda verificada do CLI, não de um teste completo ao vivo em cada backend. Operadores exclusivos do Gmail, como category:promotions e rfc822msgid:, aparecem aqui como sintaxe direta da API. Para workflows entre provedores, prefira flags do CLI como --from, --to, --subject, --after, --before e --has-attachment.

NecessidadeFormato na Gmail APIFormato no CLI
Busca por remetenteq="from:alice@example.com"nylas email search "*" --from alice@example.com
Busca de não lidosq="is:unread"nylas email search "*" --unread
Busca de anexosq="has:attachment"nylas email search "*" --has-attachment
Janela de datasq="invoice after:2026/01/01 before:2026/02/01"nylas email search "invoice" --after 2026-01-01 --before 2026-02-01

Como labels, pastas e categorias afetam a qualidade da busca?

A qualidade da busca no Gmail depende de escolher o conceito de caixa de correio certo: labels, pastas ou categorias. Labels do Gmail são tags muitos-para-muitos, pastas de provedor costumam ser um único local e categorias do Gmail são labels de sistema atribuídas pelo Google. Misturar esses 3 conceitos de caixa é um motivo comum para buscas retornarem mensagens demais ou deixarem passar mensagens esperadas.

Use a busca de texto completo quando o usuário lembra de palavras da mensagem. Use labels quando o seu workflow já classificou as mensagens. Use categorias quando o alvo é uma aba do Gmail, como Promoções ou Social. Use pastas quando você quer um comando neutro de provedor que também mapeia bem para Outlook, Exchange, Yahoo, iCloud e IMAP.

Um padrão em 2 etapas costuma ser o mais fácil de depurar: liste primeiro as pastas ou labels disponíveis e depois busque dentro do local escolhido. Isso mantém o nome da pasta visível nos logs e evita fixar no código uma label exclusiva do Gmail onde um workflow entre provedores deveria usar a abstração de pastas do CLI.

Como testar consultas de busca do Gmail antes de colocar um job em produção?

Teste consultas de busca do Gmail com um ciclo de 4 verificações antes de colocá-las em cron, CI ou uma ferramenta de agente: rode com um limite pequeno, inspecione os IDs, leia 1 mensagem selecionada e salve a string exata da consulta. Isso captura buscas amplas demais antes que elas leiam centenas de corpos de mensagem.

A primeira execução deve usar --limit 5 ou --limit 10, não o teto de produção. Confira se as 5 correspondências mais novas são o tipo de e-mail que você esperava e só então amplie o limite, depois que os filtros de remetente, data, pasta e anexo se comportarem corretamente. Para um job mensal, teste pelo menos 2 janelas de datas: uma com correspondências conhecidas e uma janela vazia.

Este teste rápido mantém a saída pequena e fácil de revisar. O primeiro comando prova que a busca está delimitada; o segundo lê um candidato. Se a mensagem selecionada estiver errada, corrija a consulta antes de adicionar paginação ou lógica de envio.

nylas email search "invoice" --from billing@example.com --limit 5 --json

nylas email read <message-id> --json

Como agentes de IA devem usar a busca do Gmail com segurança?

Agentes de IA devem usar a busca do Gmail como uma etapa de recuperação delimitada, não como permissão para ler a caixa inteira. Um loop de agente seguro busca de forma restrita, limita os candidatos, inspeciona os metadados, lê apenas as mensagens selecionadas e pede aprovação antes de qualquer envio ou ação destrutiva.

A diferença é mensurável. Um agente que busca 25 mensagens e lê 3 corpos tem um prompt, um custo e uma pegada de privacidade bem menores do que um que lê 250 corpos primeiro. A consulta de busca também vira um artefato de auditoria: revisores podem ver se o agente buscou por from:customer@example.com, has:attachment ou um termo amplo como contract.

Este padrão de shell é uma boa base para ferramentas de agente. Ele coleta 25 IDs candidatos, deixa uma etapa de ranqueamento escolher um e só então lê o conteúdo do corpo. Os nomes dos comandos se conectam de forma limpa a logs de auditoria e listas de comandos permitidos.

nylas email search "contract" --from customer@example.com --limit 25 --json \
  | jq -r '.[].id' \
  | head -5

nylas email read <selected-message-id> --json

Quando usar a Gmail API em vez do CLI?

Use a Gmail API diretamente quando a sua aplicação precisa de 1 plano de controle exclusivo do Gmail: operadores brutos de q como rfc822msgid:, administração do Gmail, propriedade de um projeto Google Cloud próprio, delegação em todo o domínio, renovação de watch via Pub/Sub ou uma interface que já incorpora o fluxo OAuth do Google. Use o CLI quando você quer um workflow de terminal, uma ferramenta de agente, um cron job ou um script multi-provedor com menos partes móveis.

A decisão não é sobre a Gmail API ser boa ou não. É sobre quem deve ser dono do encanamento. O código direto de API é dono da configuração de OAuth, da construção das consultas, da paginação, das leituras de mensagem, da decodificação de base64url, do comportamento de retry e do lock-in de provedor. O caminho do CLI é dono da seleção de comandos e do tratamento da saída, enquanto a Nylas cuida da integração com o provedor nos bastidores.

Para a maior parte da automação de desenvolvedores, comece pelo caminho do CLI e migre para chamadas diretas à Gmail API apenas quando você conseguir nomear o recurso exclusivo do Gmail. Essa regra evita que scripts pontuais, ferramentas de agente de IA e jobs de CI se tornem clientes OAuth de longa duração.

O que construir a seguir?