Google: Modifies the labels and the Classification Label values on the specified message For administrators modifying message for users in their organization, requests require authorization with a service account (https: developers google com identity protocols O Auth2 Service Account) that has domain-wide delegation authority (https: developers google com identity protocols O Auth2 Service Account#delegatingauthority) to impersonate users with the `https: www googleapis com auth gmail modify restricted` scope

← Gmail users messages operations · Get started

Operation google.gmail_users_messages_modify

Provider route: POST /gmail/v1/users/{userId}/messages/{id}/modify. 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["gmailUsersMessages"]["gmailUsersMessagesModify"]>[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.gmailUsersMessages.gmailUsersMessagesModify(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_messages.gmail_users_messages_modify(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.id	string	Required within parent	The ID of the message to modify.
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 Modifies the labels and the Classification Label values on the specified message For administrators modifying message for users in their organization, requests require authorization with a service account (https: developers google com identity protocols O Auth2 Service Account) that has domain-wide delegation authority (https: developers google com identity protocols O Auth2 Service Account#delegatingauthority) to impersonate users with the `https: www googleapis com auth gmail modify restricted` scope — request body — body

Referenced models: Modifies the labels and the Classification Label values on the specified message For administrators modifying message for users in their organization, requests require authorization with a service account (https: developers google com identity protocols O Auth2 Service Account) that has domain-wide delegation authority (https: developers google com identity protocols O Auth2 Service Account#delegatingauthority) to impersonate users with the `https: www googleapis com auth gmail modify restricted` scope — 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 message — response body

Referenced models: Gets the specified message — response body

Schemas

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

Modifies the labels and the Classification Label values on the specified message For administrators modifying message for users in their organization, requests require authorization with a service account (https: developers google com identity protocols O Auth2 Service Account) that has domain-wide delegation authority (https: developers google com identity protocols O Auth2 Service Account#delegatingauthority) to impersonate users with the `https: www googleapis com auth gmail modify restricted` scope — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
addClassificationLabels	array	Optional	A list of classification label values to add. If a Classification Label with the same label ID is already applied to the message, fields with existing field IDs will be updated and fields with new field IDs will be added. There's a limit of 20 Classification Label values per request. If the message is already classified and the final total number of Classification Label values exceeds the maximum allowed number of Classification Label values per message, the modification fails.
addClassificationLabels[]	Model	Each item	Expand Gets the specified message — response body — classification Label Values item
addLabelIds	array	Optional	A list of IDs of labels to add to this message. You can add up to 100 labels with each update.
addLabelIds[]	string	Each item
removeClassificationLabelIds	array	Optional	A list of Classification Label values to remove from this message.
removeClassificationLabelIds[]	string	Each item
removeLabelIds	array	Optional	A list IDs of labels to remove from this message. You can remove up to 100 labels with each update.
removeLabelIds[]	string	Each item

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

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_messages_modify. Catalog operation: gmail.users.messages.modify. 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.modify"]

Official provider source