Guide

Exemples de requêtes de recherche API Gmail

Exemples de requêtes de recherche de l'API Gmail pour le paramètre q, les libellés, catégories, dates, pièces jointes et rfc822msgid. Voyez la syntaxe API directe, puis traduisez les cas courants en filtres CLI supportés.

Written by Qasim Muhammad Staff SRE

Reviewed by Nick Barraclough

Verified — CLI 3.1.11 · last tested May 16, 2026

Comment fonctionne la syntaxe des requêtes de recherche de l'API Gmail ?

La syntaxe des requêtes de recherche de l'API Gmail repose sur le passage d'une expression de recherche Gmail dans le paramètre de requête q de users.messages.list. Google documente que ce paramètre supporte le même format de requête que la barre de recherche Gmail : une seule requête HTTP peut donc filtrer par expéditeur, destinataire, objet, statut non lu, date, présence de pièce jointe et identifiant de message.

La limitation clé est que messages.list renvoie des identifiants de messages, pas les corps complets. La méthode renvoie 100 résultats par défaut et accepte jusqu'à 500 résultats par page : une recherche qui renvoie 1 500 correspondances exige donc au moins 3 appels de liste avant de récupérer le moindre contenu. La référence officielle users.messages.list précise aussi que q ne peut pas être utilisé avec le scope gmail.metadata.

Cet exemple Python minimal montre la forme directe de l'API. Il recherche les messages non lus d'un expéditeur, plafonne la première page à 50 identifiants et laisse la lecture des corps de messages pour une seconde étape. Cette séparation compte, car chaque lecture de corps est un appel API supplémentaire.

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", [])]

Comment rechercher par expéditeur, destinataire, objet et statut non lu ?

Les requêtes de recherche Gmail combinent des opérateurs de champ dans une seule chaîne : les filtres expéditeur, destinataire, objet et non lu peuvent donc cohabiter dans la même valeur q. La bonne pratique consiste à garder la requête étroite avant que la pagination ne commence, car chaque résultat supplémentaire peut devenir un appel messages.get de plus par la suite.

Les exemples de Google incluent des opérateurs tels que from:, rfc822msgid: et is:unread. L'interface Gmail supporte aussi to:, subject:, les expressions exactes et la négation. Dans le code API, les opérateurs ne sont qu'une chaîne encodée en URL ; le serveur exécute la recherche et renvoie les identifiants des messages correspondants. Un plafond de 25 résultats est un bon premier passage pour les jobs d'agents ou de cron : il fournit assez de candidats sans imposer une lecture complète de la boîte mail.

Cette commande CLI utilise des flags vérifiés de nylas email search. La requête positionnelle est invoice, car la commande actuelle traite une requête sans wildcard comme du texte d'objet ; les opérateurs de champ comme from: relèvent de la syntaxe de l'API Gmail, pas d'un passage brut au CLI. La commande renvoie 25 résultats JSON pour les scripts ou les outils d'agents.

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

Comment fonctionnent les recherches par libellés et catégories Gmail ?

Les libellés Gmail ne sont pas des dossiers ; ce sont des étiquettes qui peuvent apparaître sur de nombreux messages, et un même message peut porter plusieurs libellés à la fois. Google documente 2 familles de libellés : les libellés SYSTEM réservés comme INBOX, et les libellés USER personnalisés créés par le propriétaire de la boîte mail ou une intégration.

Le guide des libellés Gmail liste les libellés système courants, dont INBOX, SPAM, TRASH, UNREAD, STARRED, et 5 libellés de catégorie tels que CATEGORY_PERSONAL, CATEGORY_SOCIAL, CATEGORY_PROMOTIONS, CATEGORY_UPDATES et CATEGORY_FORUMS. Les requêtes de recherche utilisent souvent la syntaxe orientée utilisateur comme category:promotions, tandis que les filtres de libellés de l'API utilisent des identifiants comme CATEGORY_PROMOTIONS.

Le CLI expose les libellés de catégorie Gmail via la même interface de type dossier utilisée pour les autres fournisseurs. Cet exemple recherche 25 messages de l'onglet Promotions, puis lance une recherche par objet sur les messages Réseaux sociaux. Les deux commandes utilisent --in, le filtre de dossier vérifié de nylas email search.

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

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

Comment rechercher des pièces jointes sans décoder le MIME d'abord ?

Les recherches de pièces jointes Gmail doivent commencer par l'index de recherche, pas par l'analyse MIME. La requête has:attachment réduit l'ensemble de résultats avant que votre code ne télécharge les payloads des messages, ce qui évite de décoder chaque message d'une grande boîte de réception pour découvrir que seuls 3 messages contiennent des fichiers.

Le téléchargement des pièces jointes reste une seconde étape API. La ressource de pièces jointes Gmail décrit attachmentId comme la valeur utilisée dans une requête messages.attachments.get distincte, et les données renvoyées sont encodées en base64url. Une intégration Gmail directe doit donc gérer la recherche, le parcours des parties du message, la récupération de l'identifiant de pièce jointe, le décodage des octets et l'écriture du fichier.

Le CLI garde le premier passage léger et diffère le téléchargement du fichier jusqu'à ce que vous sélectionniez un message et un identifiant de pièce jointe. Ces 3 commandes recherchent les messages porteurs de pièces jointes, listent les pièces jointes d'un message sélectionné, puis téléchargent une pièce jointe précise vers un chemin 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

Comment rechercher des plages de dates et d'anciens messages ?

Les recherches par date dans Gmail utilisent des opérateurs comme after:, before:, older: et newer: au sein de l'expression de recherche, tandis que le CLI expose les bornes de dates sous forme de flags explicites. Dans les deux cas, l'automatisation doit utiliser des dates fixes pour qu'un même job produise des résultats reproductibles d'une exécution à l'autre sur 24 heures.

Des fenêtres fixes évitent les balayages cachés de la boîte mail. Un job de facturation mensuel peut chercher uniquement janvier 2026, puis lire les messages sélectionnés après classement par objet et expéditeur. Dans le code API, cette plage de dates vit dans la chaîne q. Dans le CLI, --after et --before rendent les bornes de dates visibles pour un relecteur et faciles à imposer dans un wrapper.

Cette commande recherche les messages dont l'objet contient « invoice » entre le 1er janvier et le 1er février 2026. Elle renvoie au plus 50 candidats, ce qui suffit pour un rapport humain ou une passe de classement par un agent, sans laisser l'étape de récupération s'étendre à des milliers de corps de messages.

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

Comment retrouver un message précis avec rfc822msgid ?

L'opérateur rfc822msgid: recherche un identifiant de message Internet spécifique, ce qui est utile quand un webhook, un bounce, une ligne de log ou un ticket de support enregistre l'en-tête Message-ID d'origine. Au lieu de balayer par objet, la recherche cible un identifiant globalement significatif qui correspond normalement à 1 conversation.

Google inclut rfc822msgid: dans les exemples de la documentation de users.messages.list. L'opérateur est surtout utile pour déboguer les envois en double, le fan-out de webhooks et le fil des réponses, car il contourne la recherche textuelle approximative. Le résultat peut tout de même inclure plus de 1 message si des copies existent à travers les libellés ou les vues de conversation : gardez une limite basse et inspectez les identifiants avant de lire les corps.

Le CLI n'expose pas actuellement de passage brut du q Gmail pour rfc822msgid:. Utilisez l'API Gmail directe pour cet opérateur précis, et n'utilisez les flags CLI que lorsque vous pouvez approximer la recherche avec des filtres d'expéditeur, d'objet, de date, de dossier ou de pièce jointe. Cet exemple plafonne le résultat API à 5 identifiants.

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", [])]

Comment paginer les résultats de recherche Gmail en toute sécurité ?

Une pagination sûre des recherches Gmail garde la requête stable, stocke le nextPageToken courant et s'arrête dès que la limite métier est atteinte. L'API autorise jusqu'à 500 résultats par page, mais les jobs de production devraient en général définir un plafond total plus petit, comme 200 ou 1 000 messages.

La pagination est l'endroit où le code API direct grossit vite. Il vous faut une boucle pour nextPageToken, un plafond de résultats, un comportement de retry pour les échecs transitoires et un moyen de reprendre sans retraiter deux fois la même page. Si un job quotidien n'a besoin que des 200 reçus les plus récents, récupérer 2 000 correspondances augmente le coût en quota et le temps de relecture sans améliorer le résultat.

Cette boucle Python garde la requête de recherche constante et s'arrête après 200 identifiants de messages. Elle illustre l'état supplémentaire qu'une intégration directe doit gérer avant même de pouvoir appeler messages.get pour les objets, extraits ou corps.

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

Comment transformer les résultats de recherche Gmail en messages lisibles ?

Les résultats de recherche Gmail ne deviennent lisibles qu'après une seconde étape de récupération, car messages.list renvoie des enregistrements de messages allégés. Pour afficher un objet, un expéditeur, un extrait ou un corps, le code doit appeler messages.get pour les identifiants sélectionnés, puis parser les en-têtes et les données de payload encodées en base64url.

C'est la partie que beaucoup d'exemples cachent. Une recherche renvoyant 50 identifiants de messages peut se transformer en 50 appels de suivi si votre workflow lit chaque correspondance. Pour les workflows d'agents, un schéma plus sûr consiste à chercher d'abord, classer les métadonnées, lire 1 à 5 messages sélectionnés, puis s'arrêter. Le CLI reflète cette frontière de récupération avec les commandes distinctes nylas email search et nylas email read.

Ces commandes cherchent d'abord, puis lisent un message choisi. Cette forme en 2 étapes est intentionnelle : elle permet à un script ou à un modèle d'inspecter les identifiants et extraits avant de dépenser d'autres appels sur le contenu des corps.

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

nylas email read <message-id> --json

Comment le CLI mappe-t-il la recherche entre fournisseurs ?

Le CLI offre aux développeurs une seule commande de recherche alors que 6 familles de fournisseurs conservent leurs propres moteurs de recherche et modèles de boîte mail. Gmail a q et les libellés, la messagerie Microsoft a le filtrage Graph et les API de dossiers, et les serveurs IMAP exposent SEARCH plus des dossiers de boîte mail. Le contrat utile est une surface de commande unique avec le comportement propre à chaque fournisseur masqué derrière.

Le comportement côté fournisseur décrit dans ce guide provient de la documentation Google et de l'aide vérifiée du CLI, pas d'un test de bout en bout sur chaque backend. Les opérateurs propres à Gmail comme category:promotions et rfc822msgid: relèvent ici de la syntaxe API directe. Pour les workflows multi-fournisseurs, privilégiez les flags CLI comme --from, --to, --subject, --after, --before et --has-attachment.

BesoinForme API GmailForme CLI
Recherche par expéditeurq="from:alice@example.com"nylas email search "*" --from alice@example.com
Recherche des non lusq="is:unread"nylas email search "*" --unread
Recherche de pièces jointesq="has:attachment"nylas email search "*" --has-attachment
Fenêtre de datesq="invoice after:2026/01/01 before:2026/02/01"nylas email search "invoice" --after 2026-01-01 --before 2026-02-01

Comment les libellés, dossiers et catégories influencent-ils la qualité de recherche ?

La qualité d'une recherche Gmail dépend du choix du bon concept de boîte mail : libellés, dossiers ou catégories. Les libellés Gmail sont des étiquettes plusieurs-à-plusieurs, les dossiers des fournisseurs sont habituellement un emplacement unique, et les catégories Gmail sont des libellés système attribués par Google. Mélanger ces 3 concepts de boîte mail est une raison fréquente pour laquelle des recherches renvoient trop de messages ou manquent des messages attendus.

Utilisez la recherche plein texte quand l'utilisateur se souvient de mots du message. Utilisez les libellés quand votre workflow a déjà classé les messages. Utilisez les catégories quand la cible est un onglet Gmail comme Promotions ou Réseaux sociaux. Utilisez les dossiers quand vous voulez une commande neutre vis-à-vis du fournisseur qui se transpose aussi bien vers Outlook, Exchange, Yahoo, iCloud et IMAP.

Un schéma en 2 étapes est en général le plus facile à déboguer : listez d'abord les dossiers ou libellés disponibles, puis cherchez dans l'emplacement choisi. Cela garde le nom du dossier visible dans les logs et évite de coder en dur un libellé propre à Gmail là où un workflow multi-fournisseur devrait utiliser l'abstraction de dossiers du CLI.

Comment tester les requêtes de recherche Gmail avant de déployer un job ?

Testez les requêtes de recherche Gmail avec une boucle de 4 vérifications avant de les mettre dans cron, la CI ou un outil d'agent : exécutez avec une petite limite, inspectez les identifiants, lisez 1 message sélectionné et sauvegardez la chaîne de requête exacte. Cela détecte les recherches trop larges avant qu'elles ne lisent des centaines de corps de messages.

La première exécution doit utiliser --limit 5 ou --limit 10, pas le plafond de production. Vérifiez que les 5 correspondances les plus récentes sont bien le type de courrier attendu, puis élargissez la limite seulement après que les filtres d'expéditeur, de date, de dossier et de pièce jointe se comportent correctement. Pour un job mensuel, testez au moins 2 fenêtres de dates : une avec des correspondances connues et une fenêtre vide.

Ce test de fumée garde une sortie réduite et facile à relire. La première commande prouve que la recherche est bien délimitée ; la seconde lit un candidat. Si le message sélectionné est le mauvais, corrigez la requête avant d'ajouter la pagination ou la logique d'envoi.

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

nylas email read <message-id> --json

Comment les agents IA doivent-ils utiliser la recherche Gmail en sécurité ?

Les agents IA doivent utiliser la recherche Gmail comme une étape de récupération bornée, pas comme une permission de lire toute la boîte mail. Une boucle d'agent sûre cherche de façon étroite, limite les candidats, inspecte les métadonnées, ne lit que les messages sélectionnés et demande une approbation avant tout envoi ou action destructive.

La différence est mesurable. Un agent qui cherche 25 messages et lit 3 corps a une empreinte de prompt, de coût et de confidentialité bien plus petite qu'un agent qui lit d'abord 250 corps. La requête de recherche devient aussi un artefact d'audit : les relecteurs peuvent voir si l'agent a cherché from:customer@example.com, has:attachment ou un terme large comme contract.

Ce schéma shell est une bonne base pour les outils d'agents. Il collecte 25 identifiants candidats, laisse une étape de classement en choisir un, et lit alors seulement le contenu du corps. Les noms de commandes se relient proprement aux logs d'audit et aux listes d'autorisation de commandes.

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

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

Quand utiliser l'API Gmail plutôt que le CLI ?

Utilisez l'API Gmail directement quand votre application a besoin d'1 plan de contrôle propre à Gmail : opérateurs q bruts comme rfc822msgid:, administration Gmail, propriété Google Cloud personnalisée, délégation à l'échelle du domaine, renouvellement de watch Pub/Sub, ou une interface qui intègre déjà le flux OAuth de Google. Utilisez le CLI quand vous voulez un workflow terminal, un outil d'agent, un job cron ou un script multi-fournisseur avec moins de pièces mobiles.

La décision ne porte pas sur la qualité de l'API Gmail. Elle porte sur qui doit posséder la plomberie. Le code API direct possède la configuration OAuth, la construction des requêtes, la pagination, les lectures de messages, le décodage base64url, le comportement de retry et le verrouillage fournisseur. La voie CLI possède le choix des commandes et le traitement de la sortie, tandis que Nylas gère l'intégration fournisseur en coulisses.

Pour la plupart des automatisations de développeurs, commencez par la voie CLI et ne passez aux appels directs de l'API Gmail que lorsque vous pouvez nommer la fonctionnalité propre à Gmail. Cette règle évite que les scripts ponctuels, les outils d'agents IA et les jobs CI ne deviennent des clients OAuth à longue durée de vie.

Que construire ensuite ?