Enumera los mensajes de Gmail

En este documento, se explica cómo llamar al método messages.list de la API de Gmail.

El método muestra un array de objetos messages de Gmail que contienen el id y el threadId del mensaje. Para recuperar los detalles completos del mensaje, usa el messages.get método.

Requisitos previos

Python

Un proyecto de Google Cloud con la API de Gmail habilitada. Para conocer los pasos, completa la guía de inicio rápido de la API de Gmail para Python.

Mostrar mensajes

El método messages.list admite varios parámetros de consulta para filtrar los mensajes:

  • maxResults: Es la cantidad máxima de mensajes que se mostrarán (el valor predeterminado es 100 y el máximo es 500).
  • pageToken: Es el token para recuperar una página específica de resultados.
  • q: Es la cadena de consulta para filtrar mensajes, como from:someuser@example.com is:unread.
  • labelIds: Solo muestra los mensajes con etiquetas que coincidan con todos los IDs de etiquetas especificados.
  • includeSpamTrash: Incluye mensajes de SPAM y TRASH en los resultados.

Muestra de código

Python

En la siguiente muestra de código, se muestra cómo enumerar los mensajes del usuario autenticado de Gmail. El código controla la paginación para recuperar todos los mensajes que coinciden con la consulta.

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

El método messages.list muestra un cuerpo de respuesta que contiene lo siguiente:

  • messages[]: Es un array de recursos Message.
  • nextPageToken: Para las solicitudes con varias páginas de resultados, es un token que se puede usar con llamadas posteriores para mostrar más mensajes.
  • resultSizeEstimate: Es una cantidad total estimada de resultados.

Para obtener el contenido y los metadatos completos del mensaje, usa el campo message.id para llamar al messages.get método.