API Gmail : lister spam et corbeille

Références de commandes utilisées dans ce guide : nylas email list et nylas email folders list.

Pourquoi l'API Gmail ne renvoie-t-elle pas les messages du spam ou de la corbeille ?

L'API Gmail exclut par défaut les libellés système SPAM et TRASH des réponses de users.messages.list. Le paramètre de requête includeSpamTrash contrôle ce comportement, vaut false par défaut et, selon la référence messages.list, va "include messages from SPAM and TRASH in the results" (inclure les messages de SPAM et TRASH dans les résultats) lorsqu'il est défini à true.

Ce comportement par défaut convient aux applications de type boîte de réception, mais il casse trois usages réels : l'analyse d'abus et de phishing, la sauvegarde complète de la boîte mail et les scripts de récupération de faux positifs. Chaque appel messages.list coûte 5 unités de quota et renvoie 100 identifiants de messages par défaut (500 avec maxResults) ; la correction est donc un changement de paramètre, pas des requêtes supplémentaires.

Comment inclure le spam et la corbeille avec includeSpamTrash ?

Définir includeSpamTrash=true sur messages.list renvoie les messages du spam et de la corbeille avec tout le reste. Le paramètre élargit l'ensemble de résultats au lieu de le filtrer ; utilisez-le quand vous avez besoin d'un balayage complet de la boîte mail. Combiné à maxResults=500, une seule requête couvre 5 fois la taille de page par défaut.

L'exemple Python ci-dessous utilise google-api-python-client et compte combien des 500 premiers résultats portent le libellé SPAM ou TRASH. Notez que chaque messages.get de suivi coûte 20 unités de quota, soit 4 fois l'appel de liste lui-même.

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']

Sans ce paramètre, le même appel élimine silencieusement tout message portant le libellé SPAM ou TRASH. Aucun avertissement, aucun décompte de ce qui a été exclu : c'est pourquoi les scripts de sauvegarde qui omettent ce flag sous-estiment la taille de la boîte mail et ratent des messages récupérables.

Comment lister uniquement les messages de spam avec labelIds ?

Passer labelIds=["SPAM"] à messages.list renvoie uniquement les messages de spam, sans avoir besoin d'includeSpamTrash. La référence de l'API précise que le filtre renvoie les messages "with labels that match all of the specified label IDs" (dont les libellés correspondent à tous les identifiants de libellés spécifiés) ; un seul identifiant de libellé vous donne donc exactement ce dossier. Utilisez ["TRASH"] de la même façon pour le courrier supprimé.

La troisième option est le paramètre q qui, selon la même référence, "supports the same query format as the Gmail search box" (supporte le même format de requête que la barre de recherche Gmail). Cela rend q="in:spam" équivalent au filtre labelIds, et il se combine avec d'autres opérateurs comme from: et after: dans une seule chaîne.

# 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()

Choisissez selon l'intention : labelIds pour une lecture propre d'un seul dossier, q quand vous devez combiner le périmètre spam avec des conditions d'expéditeur, de date ou de pièce jointe. Les deux approches coûtent les mêmes 5 unités de quota par appel de liste. SPAM et TRASH sont 2 des 13 libellés système intégrés de Gmail, listés dans le guide des libellés Gmail.

Combien de temps Gmail conserve-t-il les messages de la corbeille ?

Gmail conserve un message supprimé dans la corbeille pendant 30 jours au maximum. Selon la documentation de récupération de Google, "Up to 30 days after deletion: You can find the message in Trash" (jusqu'à 30 jours après la suppression, vous pouvez retrouver le message dans la corbeille) et après 30 jours "The message is permanently deleted." (le message est définitivement supprimé). Tout script de récupération construit sur le libellé TRASH court contre cette horloge.

Cette fenêtre détermine la planification de votre automatisation. Une tâche cron hebdomadaire qui exporte la corbeille en JSON a 4 chances d'attraper un message avant que Gmail ne le purge ; une tâche mensuelle peut rater des messages entièrement. Pour le tri du spam, le schéma pratique est le même : listez le libellé SPAM selon un calendrier plus court que la fenêtre de réponse aux incidents de votre équipe, et conservez tout ce qui pourrait vous servir de preuve.

Comment lire le spam et la corbeille depuis le CLI ?

La commande nylas email list --folder SPAM renvoie les messages de spam Gmail en JSON sans projet Google Cloud, sans écran de consentement OAuth ni installation du client Python. Le flag --folder du CLI accepte n'importe quel identifiant de libellé système Gmail ; TRASH fonctionne donc à l'identique, et --all-folders balaie tous les dossiers en une seule exécution. L'authentification tient en un seul 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

Ces commandes ont été vérifiées sur un compte Gmail réel avec le CLI 3.1.16. La même syntaxe --folder fonctionne sur les comptes Outlook et IMAP avec leurs noms de dossiers : un script de revue du spam écrit pour Gmail se porte donc vers d'autres fournisseurs sans toucher au modèle de libellés de l'API Gmail. Lancez nylas email folders list pour voir les identifiants de dossiers exacts sur n'importe quel compte connecté.

Étapes suivantes

• Requêtes de recherche de l'API Gmail — chaque opérateur q, y compris in:, label: et les filtres de date
• API des libellés Gmail — libellés système vs libellés utilisateur et comment les appliquer par programmation
• batchDelete de l'API Gmail — supprimez définitivement jusqu'à 1 000 messages par requête, avec des garde-fous
• Sauvegarder les e-mails en JSON — exportez les messages avant la fermeture de la fenêtre de 30 jours de la corbeille
• Référence complète des commandes — chaque flag et sous-commande documentés