Lister les messages Gmail

Ce document explique comment appeler la méthode messages.list de l'API Gmail.

La méthode renvoie un tableau d'objets messages Gmail contenant les id et threadId du message. Pour récupérer tous les détails d'un message, utilisez la méthode messages.get.

Prérequis

Python

Un projet Google Cloud avec l'API Gmail activée. Pour connaître la marche à suivre, consultez le démarrage rapide de l'API Gmail pour Python.

Répertorier des messages

La méthode messages.list accepte plusieurs paramètres de requête pour filtrer les messages :

  • maxResults : nombre maximal de messages à renvoyer (par défaut, 100 ; maximum, 500).
  • pageToken : jeton permettant de récupérer une page de résultats spécifique.
  • q : chaîne de requête permettant de filtrer les messages, par exemple from:someuser@example.com is:unread.
  • labelIds : n'affiche que les messages dont les libellés correspondent à tous les ID de libellé spécifiés.
  • includeSpamTrash : incluez les messages de SPAM et TRASH dans les résultats.

Exemple de code

Python

L'exemple de code suivant montre comment lister les messages de l'utilisateur Gmail authentifié. Le code gère la pagination pour récupérer tous les messages correspondant à la requête.

gmail/snippet/list_messages.py
import os.path
from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError

# If modifying these scopes, delete the file token.json.
SCOPES = ["https://www.googleapis.com/auth/gmail.readonly"]


def main():
    """Shows basic usage of the Gmail API.
    Lists the user's Gmail messages.
    """
    creds = None
    # The file token.json stores the user's access and refresh tokens, and is
    # created automatically when the authorization flow completes for the first
    # time.
    if os.path.exists("token.json"):
        creds = Credentials.from_authorized_user_file("token.json", SCOPES)
    # If there are no (valid) credentials available, let the user log in.
    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            flow = InstalledAppFlow.from_client_secrets_file("credentials.json", SCOPES)
            creds = flow.run_local_server(port=0)
        # Save the credentials for the next run
        with open("token.json", "w") as token:
            token.write(creds.to_json())

    try:
        # Call the Gmail API
        service = build("gmail", "v1", credentials=creds)
        results = (
            service.users().messages().list(userId="me", labelIds=["INBOX"]).execute()
        )
        messages = results.get("messages", [])

        if not messages:
            print("No messages found.")
            return

        print("Messages:")
        for message in messages:
            print(f'Message ID: {message["id"]}')
            msg = (
                service.users().messages().get(userId="me", id=message["id"]).execute()
            )
            print(f'  Subject: {msg["snippet"]}')

    except HttpError as error:
        # TODO(developer) - Handle errors from gmail API.
        print(f"An error occurred: {error}")


if __name__ == "__main__":
    main()

La méthode messages.list renvoie un corps de réponse contenant les éléments suivants :

  • messages[] : tableau de ressources Message.
  • nextPageToken : pour les requêtes comportant plusieurs pages de résultats, jeton pouvant être utilisé avec les appels suivants pour lister d'autres messages.
  • resultSizeEstimate : nombre total de résultats estimé.

Pour récupérer l'intégralité du contenu et des métadonnées du message, utilisez le champ message.id pour appeler la méthode messages.get.