Enumera los mensajes de Gmail

En esta página, se explica cómo llamar al método users.messages.list de la API de Gmail.

El método devuelve un array de recursos Message de Gmail que contienen los campos id y threadId del mensaje. Para recuperar los detalles completos del mensaje, usa el método users.messages.get.

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 en Python.

Mostrar mensajes

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

  • maxResults: Es la cantidad máxima de mensajes que se devolverán (el valor predeterminado es 100 y el máximo es 500).
  • pageToken: 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 devuelve mensajes con etiquetas que coincidan con todos los IDs de etiqueta especificados.
  • includeSpamTrash: Incluye mensajes de SPAM y TRASH en los resultados.

Muestra de código

Python

En el siguiente ejemplo de código, se muestra cómo enumerar los mensajes del usuario de Gmail autenticado. 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 users.messages.list devuelve 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 enumerar más mensajes.
  • resultSizeEstimate: Es la cantidad total estimada de resultados.

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