Google: Lists the drafts in the user's mailbox For more information, see Create and send draft emails (https: developers google com workspace gmail api guides drafts)

← Gmail users drafts operations · Get started

Operation google.gmail_users_drafts_list

Provider route: GET /gmail/v1/users/{userId}/drafts. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/google with npm, or alter-sdk-google with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { GoogleIntegration } from "@alter-ai/google";

async function execute(input: Parameters<GoogleIntegration["gmailUsersDrafts"]["gmailUsersDraftsList"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new GoogleIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.gmailUsersDrafts.gmailUsersDraftsList(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_google import GoogleIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = GoogleIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.gmail_users_drafts.gmail_users_drafts_list(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.userId	string	Required within parent	The user’s email address. The special value `me` can be used to indicate the authenticated user. Default: me
query	object	Optional	Additional keys: not allowed
query.fields	string	Optional	Selector specifying which fields to include in a partial response.
query.prettyPrint	boolean	Optional	Returns response with indentations and line breaks. Default: true
query.quotaUser	string	Optional	Available to use for quota purposes for server-side applications. Can be any arbitrary string assigned to a user, but should not exceed 40 characters.
query.includeSpamTrash	boolean	Optional	Include drafts from `SPAM` and `TRASH` in the results. Default: false
query.maxResults	integer	Optional	Maximum number of drafts to return. This field defaults to 100. The maximum allowed value for this field is 500. Default: 100 Format: uint32
query.pageToken	string	Optional	Page token to retrieve a specific page of results in the list.
query.q	string	Optional	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: is:unread”`.

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Lists the drafts in the user’s mailbox For more information, see Create and send draft emails (https: developers google com workspace gmail api guides drafts) — response body

Referenced models: Lists the drafts in the user’s mailbox For more information, see Create and send draft emails (https: developers google com workspace gmail api guides drafts) — response body

Schemas

Lists the drafts in the user's mailbox For more information, see Create and send draft emails (https: developers google com workspace gmail api guides drafts) — response body

Field	Type	Presence	Description and constraints
$	object	Root
drafts	array	Optional	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.
drafts[]	Model	Each item	Expand Gets the specified draft For more information, see Create and send draft emails (https: developers google com workspace gmail api guides drafts) — response body
nextPageToken	string	Optional	Token to retrieve the next page of results in the list.
resultSizeEstimate	JSON	Optional
resultSizeEstimate (anyOf 1)	integer	Alternative	Estimated total number of results. Format: uint32
resultSizeEstimate (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Referenced models: Gets the specified draft For more information, see Create and send draft emails (https: developers google com workspace gmail api guides drafts) — response body

Gets the specified draft For more information, see Create and send draft emails (https: developers google com workspace gmail api guides drafts) — response body

Field	Type	Presence	Description and constraints
$	object	Root	A draft email in the user's mailbox.
id	string	Optional	The immutable ID of the draft.
message	Model	Optional	Expand Gets the specified message — response body The message content of the draft.

Referenced models: Gets the specified message — response body

Gets the specified message — response body

Field	Type	Presence	Description and constraints
$	object	Root	An email message.
classificationLabelValues	array	Optional	Classification Label values on the message. Available Classification Label schemas can be queried using the Google Drive Labels API. Each classification label ID must be unique. If duplicate IDs are provided, only one will be retained, and the selection is arbitrary. Only used for Google Workspace accounts. There's a limit of 20 Classification Label values per request. If the Classification Label values exceeds the maximum allowed number, the request fails.
classificationLabelValues[]	Model	Each item	Expand Gets the specified message — response body — classification Label Values item
historyId	string	Optional	The ID of the last history record that modified this message. Format: uint64
id	string	Optional	The immutable ID of the message.
internalDate	string	Optional	The internal message creation timestamp (epoch ms), which determines ordering in the inbox. For normal SMTP-received email, this represents the time the message was originally accepted by Google, which is more reliable than the `Date` header. However, for API-migrated mail, it can be configured by client to be based on the `Date` header. Format: int64
labelIds	array	Optional	List of IDs of labels applied to this message.
labelIds[]	string	Each item
payload	Model	Optional	Expand Gets the specified message — response body — payload The parsed email structure in the message parts.
raw	string	Optional	The entire email message in an RFC 2822 formatted and base64url encoded string. Returned in `messages.get` and `drafts.get` responses when the `format=RAW` parameter is supplied. @required gmail.users.drafts.create gmail.users.drafts.update Format: byte
sizeEstimate	JSON	Optional
sizeEstimate (anyOf 1)	integer	Alternative	Estimated size in bytes of the message. Format: int32
sizeEstimate (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
snippet	string	Optional	A short part of the message text.
threadId	string	Optional	The ID of the thread the message belongs to. To add a message or draft to a thread, the following criteria must be met: 1. The requested `threadId` must be specified on the `Message` or `Draft.Message` you supply with your request. 2. The `References` and `In-Reply-To` headers must be set in compliance with the [RFC 2822](https://tools.ietf.org/html/rfc2822) standard. 3. The `Subject` headers must match.

Referenced models: Gets the specified message — response body — classification Label Values item, Gets the specified message — response body — payload

Gets the specified message — response body — classification Label Values item

Field	Type	Presence	Description and constraints
$	object	Root	Classification Labels applied to the email message. Classification Labels are different from Gmail inbox labels. Only used for Google Workspace accounts. [Learn more about classification labels](https://support.google.com/a/answer/9292382).
fields	array	Optional	Field values for the given classification label ID.
fields[]	Model	Each item	Expand Gets the specified message — response body — classification Label Values item fields item
labelId	string	Optional	Required. The canonical or raw alphanumeric classification label ID. Maps to the ID field of the Google Drive Label resource.

Referenced models: Gets the specified message — response body — classification Label Values item fields item

Gets the specified message — response body — payload

Field	Type	Presence	Description and constraints
$	object	Root	A single MIME message part.
body	Model	Optional	Expand Gets the specified message attachment — response body The message part body for this part, which may be empty for container MIME message parts.
filename	string	Optional	The filename of the attachment. Only present if this message part represents an attachment.
headers	array	Optional	List of headers on this message part. For the top-level message part, representing the entire message payload, it will contain the standard RFC 2822 email headers such as `To`, `From`, and `Subject`.
headers[]	Model	Each item	Expand Gets the specified message — response body — payload headers item
mimeType	string	Optional	The MIME type of the message part.
partId	string	Optional	The immutable ID of the message part.
parts	array	Optional	The child MIME message parts of this part. This only applies to container MIME message parts, for example `multipart/*`. For non- container MIME message part types, such as `text/plain`, this field is empty. For more information, see RFC 1521.
parts[]	Model	Each item	Expand Gets the specified message — response body — payload

Referenced models: Gets the specified message — response body — payload, Gets the specified message attachment — response body, Gets the specified message — response body — payload headers item

Gets the specified message — response body — classification Label Values item fields item

Field	Type	Presence	Description and constraints
$	object	Root	Field values for a classification label.
fieldId	string	Optional	Required. The field ID for the Classification Label Value. Maps to the ID field of the Google Drive `Label.Field` object.
selection	string	Optional	Selection choice ID for the selection option. Should only be set if the field type is `SELECTION` in the Google Drive `Label.Field` object. Maps to the id field of the Google Drive `Label.Field.SelectionOptions` resource.

Gets the specified message attachment — response body

Field	Type	Presence	Description and constraints
$	object	Root	The body of a single MIME message part.
attachmentId	string	Optional	When present, contains the ID of an external attachment that can be retrieved in a separate `messages.attachments.get` request. When not present, the entire content of the message part body is contained in the data field.
data	string	Optional	The body data of a MIME message part as a base64url encoded string. May be empty for MIME container types that have no message body or when the body data is sent as a separate attachment. An attachment ID is present if the body data is contained in a separate attachment. Format: byte
size	JSON	Optional
size (anyOf 1)	integer	Alternative	Number of bytes for the message part data (encoding notwithstanding). Format: int32
size (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Gets the specified message — response body — payload headers item

Field	Type	Presence	Description and constraints
$	object	Root
name	string	Optional	The name of the header before the `:` separator. For example, `To`.
value	string	Optional	The value of the header after the `:` separator. For example, `someuser@example.com`.

Policy, approvals and errors

SDK function policy ID: google.gmail_users_drafts_list. Catalog operation: gmail.users.drafts.list. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Required provider scopes: ["https://mail.google.com/", "https://www.googleapis.com/auth/gmail.compose", "https://www.googleapis.com/auth/gmail.modify", "https://www.googleapis.com/auth/gmail.readonly"]

Official provider source