Method: users.drafts.list
Stay organized with collections
Save and categorize content based on your preferences.
Lists the drafts in the user's mailbox.
HTTP request
GET https://gmail.googleapis.com/gmail/v1/users/{userId}/drafts
The URL uses gRPC Transcoding syntax.
Path parameters
| Parameters |
userId |
string
The user's email address. The special value me can be used to indicate the authenticated user.
|
Query parameters
| Parameters |
maxResults |
integer (uint32 format)
Maximum number of drafts 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 draft messages 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".
|
includeSpamTrash |
boolean
Include drafts 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:
| JSON representation |
{
"drafts": [
{
object (Draft)
}
],
"nextPageToken": string,
"resultSizeEstimate": integer
} |
| Fields |
drafts[] |
object (Draft)
List of drafts. Note that the Message property in each Draft resource only contains an id and a threadId. The messages.get method can fetch additional message details.
|
nextPageToken |
string
Token to retrieve the next page of results in the list.
|
resultSizeEstimate |
integer (uint32 format)
Estimated total number of results.
|
Authorization scopes
Requires one of the following OAuth scopes:
https://mail.google.com/
https://www.googleapis.com/auth/gmail.modify
https://www.googleapis.com/auth/gmail.compose
https://www.googleapis.com/auth/gmail.readonly
For more information, see the Authorization guide.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-03-25 UTC.
[null,null,["Last updated 2025-03-25 UTC."],[],[],null,["# Method: users.drafts.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.ListDraftsResponse.SCHEMA_REPRESENTATION)\n- [Authorization scopes](#body.aspect)\n- [Try it!](#try-it)\n\nLists the drafts in the user's mailbox.\n\n### HTTP request\n\n`GET https://gmail.googleapis.com/gmail/v1/users/{userId}/drafts`\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 drafts 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 draft messages 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\"`. |\n| `includeSpamTrash` | `boolean` Include drafts 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| ``` { \"drafts\": [ { object (/workspace/gmail/api/reference/rest/v1/users.drafts#Draft) } ], \"nextPageToken\": string, \"resultSizeEstimate\": integer } ``` |\n\n| Fields ||\n|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `drafts[]` | `object (`[Draft](/workspace/gmail/api/reference/rest/v1/users.drafts#Draft)`)` List of drafts. Note that the `Message` property in each `Draft` resource only contains an `id` and a `threadId`. The [`messages.get`](https://developers.google.com/workspace/gmail/api/v1/reference/users/messages/get) method can fetch additional message details. |\n| `nextPageToken` | `string` 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.compose`\n- `\n https://www.googleapis.com/auth/gmail.readonly`\n\nFor more information, see the [Authorization guide](/workspace/guides/configure-oauth-consent)."]]
