Google: Creates a draft with the `DRAFT` label 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_create

Provider route: POST /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"]["gmailUsersDraftsCreate"]>[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.gmailUsersDraftsCreate(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_create(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.
body	Model	Required within parent	Expand Replaces a draft’s content For more information, see Create and send draft emails (https: developers google com workspace gmail api guides drafts) — request body — body

Referenced models: Replaces a draft’s content For more information, see Create and send draft emails (https: developers google com workspace gmail api guides drafts) — request body — body

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 Gets the specified draft For more information, see Create and send draft emails (https: developers google com workspace gmail api guides drafts) — response body

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

Schemas

5 more schemas are linked from the tables above, on the schema pages.

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

Replaces a draft's content For more information, see Create and send draft emails (https: developers google com workspace gmail api guides drafts) — request body — 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	Required within parent	Expand Replaces a draft's content For more information, see Create and send draft emails (https: developers google com workspace gmail api guides drafts) — request body — body message

Referenced models: Replaces a draft's content For more information, see Create and send draft emails (https: developers google com workspace gmail api guides drafts) — request body — body message

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

Replaces a draft's content For more information, see Create and send draft emails (https: developers google com workspace gmail api guides drafts) — request body — body message

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 Sends the specified message to the recipients in the `To`, `Cc`, and `Bcc` headers For more information, see Create and send email messages (https: developers google com workspace gmail api guides sending) — request body — body payload The parsed email structure in the message parts.
raw	string	Required within parent	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	integer	Optional	Estimated size in bytes of the message. Format: int32
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, Sends the specified message to the recipients in the `To`, `Cc`, and `Bcc` headers For more information, see Create and send email messages (https: developers google com workspace gmail api guides sending) — request body — 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

Policy, approvals and errors

SDK function policy ID: google.gmail_users_drafts_create. Catalog operation: gmail.users.drafts.create. 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.addons.current.action.compose", "https://www.googleapis.com/auth/gmail.compose", "https://www.googleapis.com/auth/gmail.modify"]

Official provider source