Guide

API do Gmail: listar spam e lixeira

Seu script lista todas as mensagens da caixa de correio, mas a amostra de phishing que você procura nunca aparece. Não é um bug no seu código. A API do Gmail exclui SPAM e TRASH dos resultados de messages.list, a menos que você os peça explicitamente. Este guia cobre as três formas documentadas de ler spam e lixeira: o parâmetro includeSpamTrash, o filtro labelIds e as buscas in:spam, além do equivalente de uma flag no CLI.

Written by Aaron de Mello Senior Engineering Manager

Verified — CLI 3.1.16 · Gmail · last tested June 6, 2026

Referências de comandos usadas neste guia: nylas email list e nylas email folders list.

Por que a API do Gmail não retorna mensagens de spam ou lixeira?

A API do Gmail exclui os marcadores de sistema SPAM e TRASH das respostas de users.messages.list por padrão. O parâmetro de consulta includeSpamTrash controla esse comportamento, tem false como padrão e, segundo a referência do messages.list vai "include messages from SPAM and TRASH in the results" quando definido como true.

O padrão faz sentido para apps no estilo caixa de entrada, mas quebra três cargas de trabalho reais: análise de abuso e phishing, backup completo da caixa de correio e scripts de recuperação de falsos positivos. Cada chamada de messages.list custa 5 unidades de cota e retorna 100 IDs de mensagem por padrão (500 com maxResults), então a correção é uma mudança de parâmetro, não requisições extras.

Como incluir spam e lixeira com includeSpamTrash?

Definir includeSpamTrash=true no messages.list retorna mensagens de spam e lixeira junto com todo o resto. Ele amplia o conjunto de resultados em vez de filtrá-lo, então use quando precisar de uma varredura completa da caixa de correio. Combinado com maxResults=500, uma requisição cobre 5x o tamanho de página padrão.

O exemplo em Python abaixo usa google-api-python-client e conta quantos dos primeiros 500 resultados carregam o marcador SPAM ou TRASH. Note que cada messages.get subsequente custa 20 unidades de cota, 4x a própria chamada de listagem.

from googleapiclient.discovery import build

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

# Include spam and trash in a full-mailbox listing
results = service.users().messages().list(
    userId="me",
    includeSpamTrash=True,
    maxResults=500,
).execute()

ids = [m["id"] for m in results.get("messages", [])]
print(f"{len(ids)} messages, spam and trash included")

# Check which labels a specific message carries
msg = service.users().messages().get(
    userId="me", id=ids[0], format="minimal"
).execute()
print(msg["labelIds"])  # e.g. ['SPAM'] or ['TRASH']

Sem o parâmetro, a mesma chamada descarta silenciosamente qualquer mensagem marcada como SPAM ou TRASH. Não há aviso nem contagem do que foi excluído, e é por isso que scripts de backup que ignoram essa flag subestimam o tamanho da caixa de correio e perdem e-mails recuperáveis.

Como listar apenas mensagens de spam com labelIds?

Passar labelIds=["SPAM"] ao messages.list retorna apenas mensagens de spam, sem precisar de includeSpamTrash. A referência da API afirma que o filtro retorna mensagens "with labels that match all of the specified label IDs", então um único ID de marcador entrega exatamente aquela pasta. Use ["TRASH"] da mesma forma para e-mails excluídos.

A terceira opção é o parâmetro q, que, segundo a mesma referência, "supports the same query format as the Gmail search box". Isso torna q="in:spam" equivalente ao filtro labelIds, e ele se combina com outros operadores como from: e after: em uma única string.

# Spam only, via labelIds
spam = service.users().messages().list(
    userId="me", labelIds=["SPAM"], maxResults=100
).execute()

# Trash only
trash = service.users().messages().list(
    userId="me", labelIds=["TRASH"], maxResults=100
).execute()

# Search-style: spam from one sender in the last week
recent = service.users().messages().list(
    userId="me", q="in:spam from:billing@suspicious.example newer_than:7d"
).execute()

Escolha pela intenção: labelIds para uma leitura limpa de uma única pasta, q quando precisar combinar o escopo de spam com condições de remetente, data ou anexo. As duas abordagens custam as mesmas 5 unidades de cota por chamada de listagem. SPAM e TRASH são 2 dos 13 marcadores de sistema integrados do Gmail, listados no guia de marcadores do Gmail.

Por quanto tempo o Gmail mantém mensagens na lixeira?

O Gmail mantém uma mensagem excluída na Lixeira por até 30 dias. Segundo a documentação de recuperação do Google, "Up to 30 days after deletion: You can find the message in Trash" e, depois de 30 dias, "The message is permanently deleted." Qualquer script de recuperação que você construir sobre o marcador TRASH está correndo contra esse relógio.

Essa janela define como você agenda a automação. Um cron job semanal que exporta a lixeira para JSON tem 4 chances de capturar uma mensagem antes de o Gmail eliminá-la; um mensal pode perder mensagens por completo. Para triagem de spam, o padrão prático é o mesmo: liste o marcador SPAM em um intervalo menor que a janela de resposta a incidentes da sua equipe e persista qualquer coisa de que possa precisar como evidência.

Como ler spam e lixeira pelo CLI?

O comando nylas email list --folder SPAM retorna as mensagens de spam do Gmail como JSON sem projeto no Google Cloud, tela de consentimento OAuth ou configuração de cliente Python. A flag --folder do CLI aceita qualquer ID de marcador de sistema do Gmail, então TRASH funciona de forma idêntica, e --all-folders varre todas as pastas em uma única execução. A autenticação leva um único nylas auth login.

# List spam messages
nylas email list --folder SPAM --limit 20

# List trash as JSON for scripting
nylas email list --folder TRASH --json --limit 50

# Sweep every folder, spam and trash included
nylas email list --all-folders --json --limit 200

# Extract sender addresses from spam for a blocklist review
nylas email list --folder SPAM --json --limit 50 | \
  jq -r '.[].from[0].email' | sort | uniq -c | sort -rn

Esses comandos foram verificados em uma conta Gmail real no CLI 3.1.16. A mesma sintaxe de --folder funciona em contas Outlook e IMAP com os nomes de pasta delas, então um script de revisão de spam escrito para o Gmail é portado para outros provedores sem tocar no modelo de marcadores da API do Gmail. Execute nylas email folders list para ver os IDs exatos de pasta em qualquer conta conectada.

Próximos passos