Method: users.threads.list
Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Lista as conversas na caixa de entrada do usuário.
Solicitação HTTP
GET https://gmail.googleapis.com/gmail/v1/users/{userId}/threads
O URL usa a sintaxe de transcodificação gRPC.
Parâmetros de caminho
| Parâmetros |
userId |
string
O endereço de e-mail do usuário. O valor especial me pode ser usado para indicar o usuário autenticado.
|
Parâmetros de consulta
| Parâmetros |
maxResults |
integer (uint32 format)
Número máximo de linhas de execução a serem retornadas. O padrão desse campo é 100. O valor máximo permitido para esse campo é 500.
|
pageToken |
string
Token de página para recuperar uma página específica de resultados na lista.
|
q |
string
Retorna apenas as linhas de execução que correspondem à consulta especificada. Suporta o mesmo formato de consulta da caixa de pesquisa do Gmail. Por exemplo, "from:someuser@example.com rfc822msgid:<somemsgid@example.com>
is:unread". O parâmetro não pode ser usado ao acessar a API usando o escopo gmail.metadata.
|
labelIds[] |
string
Retorna apenas linhas com rótulos que correspondem a todos os IDs de rótulo especificados.
|
includeSpamTrash |
boolean
Incluir linhas de SPAM e TRASH nos resultados.
|
Corpo da solicitação
O corpo da solicitação precisa estar vazio.
Corpo da resposta
Se bem-sucedido, o corpo da resposta exibirá os dados com a seguinte estrutura:
| Representação JSON |
{
"threads": [
{
object (Thread)
}
],
"nextPageToken": string,
"resultSizeEstimate": integer
} |
| Campos |
threads[] |
object (Thread)
Lista de linhas de execução. Cada recurso de linha de execução não contém uma lista de messages. A lista de messages para uma determinada linha de execução pode ser extraída usando o método threads.get.
|
nextPageToken |
string
Token da página para recuperar a próxima página de resultados na lista.
|
resultSizeEstimate |
integer (uint32 format)
Número total estimado de resultados.
|
Escopos de autorização
Requer um dos seguintes escopos do OAuth:
https://mail.google.com/
https://www.googleapis.com/auth/gmail.modify
https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/gmail.metadata
Para mais informações, consulte o guia de autorização.
Exceto em caso de indicação contrária, o conteúdo desta página é licenciado de acordo com a Licença de atribuição 4.0 do Creative Commons, e as amostras de código são licenciadas de acordo com a Licença Apache 2.0. Para mais detalhes, consulte as políticas do site do Google Developers. Java é uma marca registrada da Oracle e/ou afiliadas.
Última atualização 2025-07-25 UTC.
[null,null,["Última atualização 2025-07-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)."]]
