Lister les messages Gmail

Cette page explique comment appeler la méthode users.messages.list de l'API Gmail.

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

Prérequis

Python

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

Répertorier des messages

La méthode users.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 users.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, il s'agit d'un jeton qui peut être utilisé avec des appels ultérieurs 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 users.messages.get.