List Gmail messages

This page explains how to call the Gmail API's users.messages.list method.

The method returns an array of Gmail Message resources that contain the message id and threadId. To retrieve full message details, use the users.messages.get method.

Prerequisites

Python

A Google Cloud project with the Gmail API enabled. For steps, complete the Gmail API Python quickstart.

List messages

The users.messages.list method supports several query parameters to filter the messages:

  • maxResults: Maximum number of messages to return (defaults to 100, max 500).
  • pageToken: Token to retrieve a specific page of results.
  • q: Query string to filter messages, such as from:someuser@example.com is:unread".
  • labelIds: Only return messages with labels that match all specified label IDs.
  • includeSpamTrash: Include messages from SPAM and TRASH in the results.

Code sample

Python

The following code sample shows how to list messages for the authenticated Gmail user. The code handles pagination to retrieve all messages matching the query.

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

The users.messages.list method returns a response body that contains the following:

  • messages[]: An array of Message resources.
  • nextPageToken: For requests with multiple pages of results, a token that can be used with a subsequent calls to list more messages.
  • resultSizeEstimate: An estimated total number of results.

To fetch the full message content and metadata, use the message.id field to call the users.messages.get method.