Maximum number of threads to return. This field defaults to 100. The maximum allowed value for this field is 500.
pageToken
string
Page token to retrieve a specific page of results in the list.
q
string
Only return threads matching the specified query. Supports the same query format as the Gmail search box. For example, "from:someuser@example.com rfc822msgid:<somemsgid@example.com>
is:unread". Parameter cannot be used when accessing the api using the gmail.metadata scope.
labelIds[]
string
Only return threads with labels that match all of the specified label IDs.
includeSpamTrash
boolean
Include threads from SPAM and TRASH in the results.
Request body
The request body must be empty.
Response body
If successful, the response body contains data with the following structure:
List of threads. Note that each thread resource does not contain a list of messages. The list of messages for a given thread can be fetched using the threads.get method.
nextPageToken
string
Page token to retrieve the next page of results in the list.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-03-25 UTC."],[],[],null,["# Method: users.threads.list\n\n- [HTTP request](#body.HTTP_TEMPLATE)\n- [Path parameters](#body.PATH_PARAMETERS)\n- [Query parameters](#body.QUERY_PARAMETERS)\n- [Request body](#body.request_body)\n- [Response body](#body.response_body)\n - [JSON representation](#body.ListThreadsResponse.SCHEMA_REPRESENTATION)\n- [Authorization scopes](#body.aspect)\n- [Try it!](#try-it)\n\nLists the threads in the user's mailbox.\n\n### HTTP request\n\n`GET https://gmail.googleapis.com/gmail/v1/users/{userId}/threads`\n\nThe URL uses [gRPC Transcoding](https://google.aip.dev/127) syntax.\n\n### Path parameters\n\n| Parameters ||\n|----------|-----------------------------------------------------------------------------------------------------------|\n| `userId` | `string` The user's email address. The special value `me` can be used to indicate the authenticated user. |\n\n### Query parameters\n\n| Parameters ||\n|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `maxResults` | `integer (`[uint32](https://developers.google.com/discovery/v1/type-format)` format)` Maximum number of threads to return. This field defaults to 100. The maximum allowed value for this field is 500. |\n| `pageToken` | `string` Page token to retrieve a specific page of results in the list. |\n| `q` | `string` Only return threads matching the specified query. Supports the same query format as the Gmail search box. For example, `\"from:someuser@example.com rfc822msgid:\u003csomemsgid@example.com\u003e is:unread\"`. Parameter cannot be used when accessing the api using the gmail.metadata scope. |\n| `labelIds[]` | `string` Only return threads with labels that match all of the specified label IDs. |\n| `includeSpamTrash` | `boolean` Include threads from `SPAM` and `TRASH` in the results. |\n\n### Request body\n\nThe request body must be empty.\n\n### Response body\n\nIf successful, the response body contains data with the following structure:\n\n| JSON representation |\n|-------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| ``` { \"threads\": [ { object (/workspace/gmail/api/reference/rest/v1/users.threads#Thread) } ], \"nextPageToken\": string, \"resultSizeEstimate\": integer } ``` |\n\n| Fields ||\n|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `threads[]` | `object (`[Thread](/workspace/gmail/api/reference/rest/v1/users.threads#Thread)`)` List of threads. Note that each thread resource does not contain a list of `messages`. The list of `messages` for a given thread can be fetched using the [`threads.get`](https://developers.google.com/workspace/gmail/api/v1/reference/users/threads/get) method. |\n| `nextPageToken` | `string` Page token to retrieve the next page of results in the list. |\n| `resultSizeEstimate` | `integer (`[uint32](https://developers.google.com/discovery/v1/type-format)` format)` Estimated total number of results. |\n\n### Authorization scopes\n\nRequires one of the following OAuth scopes:\n\n- `https://mail.google.com/`\n- `\n https://www.googleapis.com/auth/gmail.modify`\n- `\n https://www.googleapis.com/auth/gmail.readonly`\n- `\n https://www.googleapis.com/auth/gmail.metadata`\n\nFor more information, see the [Authorization guide](/workspace/guides/configure-oauth-consent)."]]