Gmail

Overview

Gmail is Google’s email service, featuring spam protection, advanced search, and native integration with other Google Workspace apps for productivity. With the Gmail integration in SquadOS, your agents can send, reply, forward, and organize emails, create drafts and filters, manage labels, and automate complete communication workflows.

• Official website: https://mail.google.com/
• Composio documentation: docs.composio.dev/toolkits/gmail

Authentication

This tool uses OAuth 2.0 (OAUTH2) to connect.

Authentication is handled via OAuth — no manual credentials are needed. You authorize access to your Google account directly on Composio’s secure connection page.

How to connect in SquadOS

1. Go to Tools in the side menu (/admin/tools).
2. Open the Available tab and search for Gmail.
3. Click the card to open the details modal and hit Connect.
4. You’re taken to the secure connection page hosted by Composio, where you authorize access to your Google account (OAuth).
5. Once done, you’re sent back to SquadOS with the account connected and the tool available for your agents. (Connection-flow details in Organization Tools.)

Tip

If you manage a Google Workspace organization and want to use your own OAuth credentials (for a dedicated quota and consent-screen control), follow the How to create OAuth2 credentials for Google Apps guide from Composio before connecting.

FAQ

How do I set up custom Google OAuth credentials for Gmail?

For a step-by-step guide on creating and configuring your own Google OAuth credentials with Composio, see How to create OAuth2 credentials for Google Apps.

Why am I seeing “App is blocked” when connecting Gmail?

The OAuth client is requesting scopes that Google hasn’t verified for that client. This usually happens when you add extra scopes beyond the defaults. Remove the additional scopes from your auth config, or create your own OAuth app and submit the scopes for verification.

Why am I getting “Gmail API has not been used in project” error?

When using custom OAuth credentials, the Gmail API must be enabled in the Google Cloud project that owns those credentials. Enable it in APIs & Services in Google Cloud Console, wait a few minutes, and retry.

Why am I getting “Error 400: invalid_scope”?

The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the Google OAuth scopes docs.

Why does the OAuth consent screen show “Composio” instead of my app?

By default, the consent screen uses Composio’s OAuth app. To show your own app name and logo, create your own OAuth app with a custom redirect URL.

Why am I getting 401 errors on tool calls?

The user’s access token is no longer valid. Common causes: the user revoked access, changed their password or 2FA, a Workspace admin policy changed, or Google’s refresh token limit (~50 per account) was exceeded. Re-authenticating the user typically resolves this.

Why is my Gmail trigger slow?

Gmail triggers poll roughly every minute by default. If you need lower latency, consider using webhooks or Google Pub/Sub integrations.

Why am I getting “Quota Exhausted” or “rate limit exhausted”?

Google enforces per-minute and daily request quotas. If you’re using Composio’s default OAuth app, you share that quota with other users. Use your own OAuth app credentials to get a dedicated quota, and add exponential backoff and retries to handle transient rate limits.

How do I send an email with an attachment?

When using the Composio SDK, pass a local file path or a public URL directly as a string to the attachment field. The SDK’s auto-upload feature handles uploading the file and converting it to the required format — you do not need to construct the { s3key, name, mimetype } object manually.

Available actions

Modify email labels

GMAIL_ADD_LABEL_TO_EMAIL

Adds and/or removes specified Gmail labels for a message. Ensure message_id and all label_ids are valid (use listLabels for custom label IDs).

Input parameters

Name	Type	Required	Description
user_id	string	No	User’s email address or ‘me’ for the authenticated user.
message_id	string	Yes	Immutable ID of the message to modify. Gmail message IDs are 15-16 character hexadecimal strings. Do NOT use UUIDs, thread IDs, or internal system IDs — these will cause ‘Invalid id value’ errors. Obtain valid message IDs from GMAIL_FETCH_EMAILS, GMAIL_FETCH_MESSAGE_BY_THREAD_ID, or GMAIL_LIST_THREADS.
add_label_ids	array	No	Label IDs to add (IDs, not display names). System labels: INBOX, SPAM, TRASH, UNREAD, STARRED, IMPORTANT, CATEGORY_PERSONAL, CATEGORY_SOCIAL, CATEGORY_PROMOTIONS, CATEGORY_UPDATES, CATEGORY_FORUMS. Custom labels: call ‘listLabels’ first to get the ID (format: ‘Label_<number>’). SENT, DRAFT, CHAT are immutable.
remove_label_ids	array	No	Label IDs to remove (IDs, not display names). Same rules as add_label_ids. Common operations: to mark as read, remove ‘UNREAD’; to archive, remove ‘INBOX’.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Batch delete Gmail messages

GMAIL_BATCH_DELETE_MESSAGES

Tool to permanently delete multiple Gmail messages in bulk, bypassing Trash with no recovery possible. Use when you need to efficiently remove large numbers of emails. Use GMAIL_MOVE_TO_TRASH instead when reversibility may be needed. Always obtain explicit user confirmation and verify a sample of message IDs before executing. High-volume calls may trigger 429 or 403 errors; apply exponential backoff.

Input parameters

Name	Type	Required	Description
userId	string	No	User’s email address or ‘me’ for the authenticated user.
messageIds	array	Yes	List of Gmail message IDs to delete. Each ID must be a 15-16 character hexadecimal string. Obtain IDs from GMAIL_FETCH_EMAILS or GMAIL_LIST_THREADS.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Batch modify Gmail messages

GMAIL_BATCH_MODIFY_MESSAGES

Modify labels on multiple Gmail messages in one efficient API call. Supports up to 1,000 messages per request for bulk operations like archiving, marking as read/unread, or applying custom labels. High-volume calls may return 429 or 403; apply exponential backoff.

Input parameters

Name	Type	Required	Description
userId	string	No	User’s email address or ‘me’ for the authenticated user.
messageIds	array	Yes	List of message IDs to modify. Maximum 1,000 message IDs per request. Get message IDs from GMAIL_FETCH_EMAILS or GMAIL_LIST_THREADS.
addLabelIds	array	No	List of label IDs to add to the messages. Use label IDs, NOT label display names. System labels use their name as ID (e.g., INBOX, STARRED). Custom labels MUST use their ID (format: ‘Label_XXX’). Call GMAIL_LIST_LABELS first to get the id field.
removeLabelIds	array	No	List of label IDs to remove from the messages. Same rules as addLabelIds. Common: remove ‘UNREAD’ to mark as read, remove ‘INBOX’ to archive. Note: ‘DRAFT’ cannot be removed — use GMAIL_DELETE_DRAFT instead.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Create email draft

GMAIL_CREATE_EMAIL_DRAFT

Creates a Gmail email draft. While all fields are optional per the Gmail API, practical validation requires at least one of recipient_email, cc, or bcc and at least one of subject or body. Supports To/Cc/Bcc recipients, subject, plain/HTML body, attachments, and threading. Returns a draft_id that must be used as-is with GMAIL_SEND_DRAFT. HTTP 429 may occur on rapid creation/send sequences; apply exponential backoff.

Input parameters

Name	Type	Required	Description
cc	array	No	Carbon Copy (CC) recipients’ email addresses. Each must be a valid email address (e.g., ‘user@example.com’) or display name format (e.g., ‘John Doe <user@example.com>’).
bcc	array	No	Blind Carbon Copy (BCC) recipients’ email addresses. Same format rules as cc.
body	string	No	Email body content (plain text or HTML); is_html must be True if HTML. Can also be provided as ‘message_body’.
is_html	boolean	No	Set to True if body is already formatted HTML. When False, plain text newlines are auto-converted to &lt;br/&gt; tags.
subject	string	No	Email subject line. When creating a draft reply to an existing thread (thread_id provided), leave this empty to stay in the same thread.
user_id	string	No	User’s email address or ‘me’ for the authenticated user.
thread_id	string	No	ID of an existing Gmail thread to reply to; omit for new thread.
attachment	string	No	File(s) to attach. Accepts a single file or a list of files. Must be a dict (or list of dicts) with fields: name, mimetype, and s3key (obtained from a prior upload/download response). Total message size including attachments must be under 25 MB.
recipient_email	string	No	Primary recipient’s email address. Must be a valid email address.
extra_recipients	array	No	Additional ‘To’ recipients (not Cc or Bcc). Should only be used if recipient_email is also provided.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Create Gmail filter

GMAIL_CREATE_FILTER

Tool to create a new Gmail filter with specified criteria and actions. Use when the user wants to automatically organize incoming messages based on sender, subject, size, or other criteria. Note: you can only create a maximum of 1,000 filters per account.

Input parameters

Name	Type	Required	Description
action	object	Yes	REQUIRED. Action that the filter will perform on messages matching the criteria. At least one action field must be specified.
user_id	string	No	The user’s email address or the special value ‘me’ to indicate the authenticated user.
criteria	object	Yes	REQUIRED. Message matching criteria that determines which messages the filter will apply to. At least one criteria field must be specified.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Create label

GMAIL_CREATE_LABEL

Creates a new label with a unique name in the specified user’s Gmail account. Returns a labelId (e.g., ‘Label_123’) required for downstream tools like GMAIL_ADD_LABEL_TO_EMAIL and GMAIL_BATCH_MODIFY_MESSAGES — those tools do not accept display names.

Input parameters

Name	Type	Required	Description
user_id	string	No	The email address of the user in whose account the label will be created.
label_name	string	Yes	REQUIRED. The name for the new label. Must be unique within the account, non-blank, maximum 225 characters, cannot contain commas, and must not be a reserved system label. Forward slashes ’/’ create hierarchical nested labels (e.g., ‘Work/Projects’).
text_color	string	No	Text color for the label. Gmail only accepts colors from a predefined palette of 102 specific hex values.
background_color	string	No	Background color for the label. Must be supplied together with text_color — providing only one will cause a 400 error.
label_list_visibility	string	No	Controls how the label is displayed in the label list in the Gmail sidebar. Valid values: ‘labelShow’, ‘labelShowIfUnread’, ‘labelHide’.
message_list_visibility	string	No	Controls how messages with this label are displayed in the message list. Valid values: ‘show’ or ‘hide’.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Create Prompt Post

GMAIL_CREATE_PROMPT_POST

Send a one-shot prompt to the Sanity Content Agent. Stateless one-shot prompt endpoint. No thread management or message persistence. Ideal for simple, single-turn interactions.

Input parameters

Name	Type	Required	Description
config	object	No	Agent configuration. Controls behavior, capabilities, and document access.
format	string	No	Controls how directives in the response are formatted. Values: ‘markdown’ or ‘directives’.
message	string	Yes	The prompt message to send to the agent.
instructions	string	No	Custom instructions for the agent.
organizationId	string	Yes	Your Sanity organization ID.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Delete Draft

GMAIL_DELETE_DRAFT

Permanently deletes a specific Gmail draft using its ID with no recovery possible. Verify the correct draft_id and obtain explicit user confirmation before calling.

Input parameters

Name	Type	Required	Description
user_id	string	No	User’s email address or ‘me’ for the authenticated user.
draft_id	string	Yes	Immutable ID of the draft to delete. Must be obtained from GMAIL_LIST_DRAFTS or GMAIL_CREATE_EMAIL_DRAFT. Draft IDs typically have an ‘r’ prefix (e.g., ‘r-1234567890’).

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Delete Gmail filter

GMAIL_DELETE_FILTER

Tool to permanently delete a Gmail filter by its ID. Use when you need to remove an existing email filtering rule.

Input parameters

Name	Type	Required	Description
user_id	string	No	User’s email address or ‘me’ for the authenticated user.
filter_id	string	Yes	The ID of the filter to be deleted. Filter IDs can be obtained from the GMAIL_LIST_FILTERS action.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Delete label from account (permanent)

GMAIL_DELETE_LABEL

Permanently DELETES a user-created Gmail label from the account (not from a message). WARNING: This action DELETES the label definition itself, removing it from all messages. System labels (INBOX, SENT, UNREAD, etc.) cannot be deleted. To add/remove labels from specific messages, use GMAIL_ADD_LABEL_TO_EMAIL instead.

Input parameters

Name	Type	Required	Description
user_id	string	No	User’s email address or ‘me’ for the authenticated user.
label_id	string	Yes	ID of the user-created label to be permanently DELETED from the account. Must be a custom label ID (format: ‘Label_<id>’). System labels cannot be deleted.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Delete message

GMAIL_DELETE_MESSAGE

Permanently deletes a specific email message by its ID from a Gmail mailbox. For user_id, use ‘me’ for the authenticated user or an email address to which the authenticated user has delegated access.

Input parameters

Name	Type	Required	Description
user_id	string	No	User’s email address. The special value ‘me’ refers to the authenticated user.
message_id	string	Yes	Identifier of the email message to delete.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Delete thread

GMAIL_DELETE_THREAD

Tool to immediately and permanently delete a specified thread and all its messages. This operation cannot be undone. Use threads.trash instead for reversible deletion.

Input parameters

Name	Type	Required	Description
id	string	Yes	ID of the Thread to delete.
user_id	string	No	User’s email address. The special value ‘me’ refers to the authenticated user.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Fetch emails

GMAIL_FETCH_EMAILS

Fetches a list of email messages from a Gmail account, supporting filtering, pagination, and optional full content retrieval. Results are NOT sorted by recency; sort by internalDate client-side. The messages field may be absent or empty (valid no-results state). For large result sets, prefer ids_only=true or metadata-only listing.

Input parameters

Name	Type	Required	Description
query	string	No	Gmail advanced search query (e.g., ‘from:user subject:meeting’). Use ‘is:’ for special mail states (is:unread, is:starred) and ‘label:’ ONLY for user-created labels.
user_id	string	No	User’s email address or ‘me’ for the authenticated user.
verbose	boolean	No	If false, uses optimized concurrent metadata fetching (~75% improvement). If true, uses standard detailed message fetching. Body content and attachment details require verbose=true.
ids_only	boolean	No	If true, only returns message IDs without fetching individual message details. Fastest option for getting just message IDs.
label_ids	array	No	Filter by label IDs; only messages with all specified labels are returned (AND logic). Custom label IDs in format ‘Label_123456’, not the display name.
page_token	string	No	Token for retrieving a specific page, obtained from a previous response’s nextPageToken.
max_results	integer	No	Maximum number of messages to retrieve per page. Hard cap is 500 per page.
include_payload	boolean	No	Set to true to include full message payload (headers, body, attachments).
include_spam_trash	boolean	No	Set to true to include messages from SPAM and TRASH.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Fetch message by message ID

GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID

Fetches a specific email message by its ID. Spam/trash messages are excluded unless upstream list/search calls used include_spam_trash=true. Use internalDate (milliseconds since epoch) rather than header Date for recency checks.

Input parameters

Name	Type	Required	Description
format	string	No	Format for message content. ‘minimal’: ID, thread ID, labels only. ‘metadata’: headers and metadata without body — recommended for most use cases. ‘full’: complete MIME structure with base64url-encoded body. ‘raw’: entire RFC 2822 formatted message as base64url string.
user_id	string	No	User’s email address or ‘me’ for the authenticated user.
message_id	string	Yes	The Gmail API message ID (hexadecimal string, typically 15-16 characters). Must be obtained from Gmail API responses. Do NOT use email subjects, dates, sender names, threadId, or any fabricated value.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Fetch Message by Thread ID

GMAIL_FETCH_MESSAGE_BY_THREAD_ID

Retrieves messages from a Gmail thread using its thread_id. Returns a messages array; thread_id is not echoed in the response. Message order is not guaranteed — sort by internalDate to find oldest/newest. Concurrent bulk calls may trigger 403 or 429; cap concurrency ~10 and use exponential backoff.

Input parameters

Name	Type	Required	Description
user_id	string	No	The email address of the user.
thread_id	string	Yes	Hexadecimal thread ID from Gmail API (e.g., ‘19bf77729bcb3a44’). Obtain from GMAIL_LIST_THREADS or GMAIL_FETCH_EMAILS. Prefixes like ‘msg-f:’ or ‘thread-f:’ are auto-stripped.
page_token	string	No	Opaque page token for fetching a specific page of messages if results are paginated.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Forward email message

GMAIL_FORWARD_MESSAGE

Forward an existing Gmail message to specified recipients, preserving original body and attachments. Verify recipients and content before forwarding to avoid unintended exposure. Bulk forwarding may trigger 429/5xx rate limits; keep concurrency to 5–10 and apply backoff.

Input parameters

Name	Type	Required	Description
cc	array	No	List of email addresses to CC.
bcc	array	No	List of email addresses to BCC.
user_id	string	No	User’s email address or ‘me’ for the authenticated user.
message_id	string	Yes	Gmail message ID (hexadecimal string, e.g., ‘17f45ec49a9c3f1b’). Obtain from actions like ‘List Messages’ or ‘Fetch Emails’.
recipients	array	Yes	List of email addresses to forward the message to.
additional_text	string	No	Optional additional text to include before the forwarded content.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Get Gmail attachment

GMAIL_GET_ATTACHMENT

Retrieves a specific attachment by ID from a message in a user’s Gmail mailbox. Returns base64url-encoded binary data (up to ~25 MB). Attachments exceeding ~25 MB may be exposed as Google Drive links — use GOOGLEDRIVE_DOWNLOAD_FILE when a Drive file_id is present instead.

Input parameters

Name	Type	Required	Description
user_id	string	No	User’s email address (‘me’ for authenticated user).
file_name	string	Yes	Desired filename for the downloaded attachment.
message_id	string	Yes	Immutable ID of the message containing the attachment. Obtain from Gmail API responses.
attachment_id	string	Yes	The internal Gmail attachment ID (NOT the filename). A system-generated token string like ‘ANGjdJ8s…’. Obtain this ID from the ‘attachmentId’ field in the ‘attachmentList’ array returned by fetchEmails or fetchMessageByMessageId.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Get Auto-Forwarding Settings

GMAIL_GET_AUTO_FORWARDING

Tool to get the auto-forwarding setting for the specified account, including enabled status, forwarding email address, and message disposition.

Input parameters

Name	Type	Required	Description
user_id	string	No	The user’s email address. The special value ‘me’ can be used to indicate the authenticated user.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Get contacts

GMAIL_GET_CONTACTS

Fetches contacts (connections) for the authenticated Google account, allowing selection of specific data fields and pagination. Only covers saved contacts and ‘Other Contacts’. People API shares a per-user QPS quota; HTTP 429 requires exponential backoff (1s, 2s, 4s).

Input parameters

Name	Type	Required	Description
page_token	string	No	Token to retrieve a specific page of results, obtained from ‘nextPageToken’ in a previous response.
person_fields	string	No	Comma-separated person fields to retrieve for each contact (e.g., ‘names,emailAddresses’).
resource_name	string	No	Identifier for the person resource whose connections are listed; use ‘people/me’ for the authenticated user.
include_other_contacts	boolean	No	Include ‘Other Contacts’ in addition to regular contacts. WARNING: When True, person_fields is restricted to emailAddresses, names, phoneNumbers, and metadata only.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Get Draft

GMAIL_GET_DRAFT

Retrieves a single Gmail draft by its ID. Use this to fetch and inspect draft content before sending via GMAIL_SEND_DRAFT.

Input parameters

Name	Type	Required	Description
format	string	No	Format for the draft message: ‘minimal’ (ID/labels only), ‘full’ (complete data with parsed payload), ‘raw’ (base64url-encoded RFC 2822 format), ‘metadata’ (ID/labels/headers only).
user_id	string	No	The user’s email address. The special value me can be used to indicate the authenticated user.
draft_id	string	Yes	The ID of the draft to retrieve. Use GMAIL_LIST_DRAFTS to retrieve valid draft IDs.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Get Gmail filter

GMAIL_GET_FILTER

Tool to retrieve a specific Gmail filter by its ID. Use when you need to inspect the criteria and actions of an existing filter.

Input parameters

Name	Type	Required	Description
id	string	Yes	The ID of the filter to be fetched.
user_id	string	No	The user’s email address or the special value ‘me’ to indicate the authenticated user.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Get label details

GMAIL_GET_LABEL

Gets details for a specified Gmail label, including name, type, visibility settings, message/thread counts, and color.

Input parameters

Name	Type	Required	Description
id	string	Yes	The ID of the label to retrieve. Can be a system label (e.g., INBOX, SENT, DRAFT, UNREAD, STARRED, SPAM, TRASH) or a user-created label ID (e.g., Label_1, Label_42).
user_id	string	No	The user’s email address. The special value ‘me’ can be used to indicate the authenticated user.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Get Language Settings

GMAIL_GET_LANGUAGE_SETTINGS

Tool to retrieve the language settings for a Gmail user, including the display language preference.

Input parameters

Name	Type	Required	Description
user_id	string	No	The email address of the Gmail user whose language settings are to be retrieved, or the special value ‘me’ to indicate the currently authenticated user.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Get People

GMAIL_GET_PEOPLE

Retrieves either a specific person’s details (using resource_name) or lists ‘Other Contacts’ (if other_contacts is true), with person_fields specifying the data to return. Scope is limited to the authenticated user’s own contacts and ‘Other Contacts’ history only.

Input parameters

Name	Type	Required	Description
sources	array	No	Source types to include when retrieving other contacts. Applicable only when other_contacts is true.
page_size	integer	No	The number of ‘Other Contacts’ to return per page. Applicable only when other_contacts is true.
page_token	string	No	An opaque token from a previous response to retrieve the next page of ‘Other Contacts’ results. Applicable only when other_contacts is true.
sync_token	string	No	A token from a previous ‘Other Contacts’ list call to retrieve only changes since the last sync.
person_fields	string	No	A comma-separated field mask to restrict which fields on the person are returned. When other_contacts is true, only ‘emailAddresses’, ‘names’, ‘phoneNumbers’, ‘metadata’ are valid.
resource_name	string	No	Resource name identifying the person. Used only when other_contacts is false.
other_contacts	boolean	No	If true, retrieves ‘Other Contacts’; if false, retrieves information for the single person specified by resource_name.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Get Profile

GMAIL_GET_PROFILE

Retrieves Gmail profile information (email address, aggregate messagesTotal/threadsTotal, historyId) for a user. The returned historyId seeds incremental sync via GMAIL_LIST_HISTORY. A successful call confirms mailbox connectivity but not full mailbox access if granted scopes are narrow.

Input parameters

Name	Type	Required	Description
user_id	string	No	The email address of the Gmail user whose profile is to be retrieved, or the special value ‘me’ to indicate the currently authenticated user. Prefer ‘me’ unless explicitly targeting another account.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Get Vacation Settings

GMAIL_GET_VACATION_SETTINGS

Tool to retrieve vacation responder settings for a Gmail user, including whether out-of-office auto-replies are configured and their content.

Input parameters

Name	Type	Required	Description
user_id	string	No	The email address of the Gmail user whose vacation settings are to be retrieved, or the special value ‘me’ to indicate the currently authenticated user.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Import message

GMAIL_IMPORT_MESSAGE

Tool to import a message into the user’s mailbox with standard email delivery scanning and classification. Use when you need to add an existing email to a Gmail account without sending it through SMTP. This method doesn’t perform SPF checks, so it might not work for some spam messages.

Input parameters

Name	Type	Required	Description
raw	string	Yes	The entire email message in RFC 2822 format, base64url-encoded.
deleted	boolean	No	Mark the email as permanently deleted (not TRASH) and only visible in Google Vault to a Vault administrator. Only used for Google Workspace accounts.
user_id	string	No	The user’s email address. The special value ‘me’ can be used to indicate the authenticated user.
never_mark_spam	boolean	No	Ignore the Gmail spam classifier decision and never mark this email as SPAM in the mailbox.
internal_date_source	string	No	Source for Gmail’s internal date of the message. Values: ‘receivedTime’ or ‘dateHeader’.
process_for_calendar	boolean	No	Process calendar invites in the email and add any extracted meetings to the Google Calendar for this user.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Insert message into mailbox

GMAIL_INSERT_MESSAGE

Tool to insert a message into the user’s mailbox similar to IMAP APPEND. Use when you need to add an email directly to a mailbox bypassing most scanning and classification. This does not send a message.

Input parameters

Name	Type	Required	Description
raw	string	Yes	The entire email message in RFC 2822 formatted and base64url encoded string.
deleted	boolean	No	Mark the email as permanently deleted (not TRASH) and only visible in Google Vault to a Vault administrator. Only used for Google Workspace accounts.
user_id	string	No	The user’s email address. The special value ‘me’ can be used to indicate the authenticated user.
internalDateSource	string	No	Source for Gmail’s internal date of the message. Values: ‘receivedTime’ or ‘dateHeader’.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

List CSE identities

GMAIL_LIST_CSE_IDENTITIES

Tool to list client-side encrypted identities for an authenticated user, including key pair associations.

Input parameters

Name	Type	Required	Description
user_id	string	No	The requester’s primary email address. Use ‘me’ to indicate the authenticated user.
page_size	integer	No	The number of identities to return. Default: 20.
page_token	string	No	Pagination token indicating which page of identities to return.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

List CSE key pairs

GMAIL_LIST_CSE_KEYPAIRS

Tool to list client-side encryption key pairs for an authenticated user, including public keys and enablement states. Supports pagination for large result sets.

Input parameters

Name	Type	Required	Description
user_id	string	No	The requester’s primary email address. Use ‘me’ to indicate the authenticated user.
page_size	integer	No	The number of key pairs to return per page. Default: 20.
page_token	string	No	Pagination token indicating which page of key pairs to return. Omit to return the first page.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

List Drafts

GMAIL_LIST_DRAFTS

Retrieves a paginated list of email drafts from a user’s Gmail account. Use verbose=true to get full draft details including subject, body, sender, and timestamp. Draft ordering is non-guaranteed; iterate using page_token until it is absent to retrieve all drafts.

Input parameters

Name	Type	Required	Description
user_id	string	No	User’s mailbox ID; use ‘me’ for the authenticated user.
verbose	boolean	No	If true, fetches full draft details including subject, sender, recipient, body, and timestamp. If false, returns only draft IDs (faster).
page_token	string	No	Token from a previous response to retrieve a specific page of drafts.
max_results	integer	No	Maximum number of drafts to return per page.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

List Gmail filters

GMAIL_LIST_FILTERS

Tool to list all Gmail filters (rules) in the mailbox. Use for security audits to detect malicious filter rules or before creating new filters to avoid duplicates.

Input parameters

Name	Type	Required	Description
user_id	string	No	The user’s email address or the special value ‘me’ to indicate the authenticated user whose filters will be retrieved.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

List forwarding addresses

GMAIL_LIST_FORWARDING_ADDRESSES

Tool to list all forwarding addresses for the specified Gmail account — the email addresses that are allowed to be used for forwarding messages.

Input parameters

Name	Type	Required	Description
user_id	string	No	The user’s email address or the special value ‘me’ to indicate the authenticated user.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

List Gmail history

GMAIL_LIST_HISTORY

Tool to list Gmail mailbox change history since a known startHistoryId. Use for incremental mailbox syncs. Persist the latest historyId as a checkpoint across sessions. An empty history list in the response is valid and means no new changes occurred.

Input parameters

Name	Type	Required	Description
user_id	string	No	The user’s email address. Use ‘me’ to specify the authenticated user.
label_id	string	No	Only return history records involving messages with this label ID.
page_token	string	No	Token to retrieve a specific page of results. Loop requests using this parameter until no nextPageToken is returned.
max_results	integer	No	Maximum number of history records to return. Default is 100; max is 500.
history_types	array	No	Filter by specific history types. Allowed values: messageAdded, messageDeleted, labelAdded, labelRemoved.
start_history_id	string	Yes	Required. Returns history records after this ID. If the ID is invalid or too old, the API returns 404; perform a full sync in that case.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

List Gmail labels

GMAIL_LIST_LABELS

Retrieves all system and user-created labels for a Gmail account in a single unpaginated response. Primary use: obtain internal label IDs (e.g., ‘Label_123’) required by other Gmail tools — display names cannot be used as label identifiers. Do not hardcode label IDs across sessions; refresh via this tool on conflict errors.

Input parameters

Name	Type	Required	Description
user_id	string	No	Identifies the Gmail account (owner’s email or ‘me’) for which labels will be listed.
include_details	boolean	No	If true, fetches detailed info for each label including message/thread counts. If false (default), returns basic label info which is faster.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

List Gmail messages (Deprecated)

GMAIL_LIST_MESSAGES

DEPRECATED: Use GMAIL_FETCH_EMAILS instead. Lists the messages in the user’s mailbox with optional filtering by labels or search query.

Input parameters

Name	Type	Required	Description
q	string	No	Only return messages matching the specified query. Supports the same query format as the Gmail search box.
user_id	string	No	The user’s email address or ‘me’ to specify the authenticated user.
label_ids	array	No	Only return messages with labels that match all of the specified label IDs.
page_token	string	No	Page token to retrieve a specific page of results in the list.
max_results	integer	No	Maximum number of messages to return. Defaults to 100. The maximum allowed value is 500.
include_spam_trash	boolean	No	Include messages from SPAM and TRASH in the results. Default is false.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

List send-as aliases

GMAIL_LIST_SEND_AS

Lists the send-as aliases for a Gmail account, including the primary address and custom ‘from’ aliases. Use when you need to retrieve available sending addresses for composing emails.

Input parameters

Name	Type	Required	Description
user_id	string	No	The user’s email address or the special value ‘me’ to indicate the authenticated user whose send-as aliases will be retrieved.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

List S/MIME configs

GMAIL_LIST_SMIME_INFO

Lists S/MIME configs for the specified send-as alias, including all S/MIME certificate configurations associated with a specific send-as email address.

Input parameters

Name	Type	Required	Description
user_id	string	No	The user’s email address. The special value ‘me’ can be used to indicate the authenticated user.
send_as_email	string	Yes	The email address that appears in the ‘From:’ header for mail sent using this alias.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

List threads

GMAIL_LIST_THREADS

Retrieves a list of email threads from a Gmail account, supporting filtering and pagination. Spam and trash are excluded by default unless explicitly targeted via label:spam or label:trash in the query.

Input parameters

Name	Type	Required	Description
query	string	No	Filter for threads, using Gmail search query syntax (e.g., ‘from:user@example.com is:unread’). Dates must use YYYY/MM/DD format.
user_id	string	No	The user’s email address or ‘me’ to specify the authenticated Gmail account.
verbose	boolean	No	If false, returns threads with basic fields (id, snippet, historyId). If true, returns threads with complete message details.
page_token	string	No	Token from a previous response to retrieve a specific page of results; omit for the first page.
max_results	integer	No	Maximum number of threads to return. Hard cap is ~500 per call.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Modify thread labels

GMAIL_MODIFY_THREAD_LABELS

Adds or removes specified existing label IDs from a Gmail thread, affecting all its messages. To modify a single message only, use a message-level tool instead.

Input parameters

Name	Type	Required	Description
user_id	string	No	User’s email address or ‘me’ for the authenticated user.
thread_id	string	Yes	Immutable ID of the thread to modify.
add_label_ids	array	No	List of label IDs to add to the thread. System labels use uppercase names (e.g., ‘INBOX’, ‘STARRED’). Custom labels use format ‘Label_N’. Use GMAIL_LIST_LABELS to discover available label IDs.
remove_label_ids	array	No	List of label IDs to remove from the thread. Same rules as add_label_ids.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Trash thread

GMAIL_MOVE_THREAD_TO_TRASH

Moves the specified thread to the trash. Any messages that belong to the thread are also moved to the trash.

Input parameters

Name	Type	Required	Description
user_id	string	No	The user’s email address. The special value ‘me’ can be used to indicate the authenticated user.
thread_id	string	Yes	Required. The ID of the thread to trash. This moves all messages in the thread to trash.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Move to Trash

GMAIL_MOVE_TO_TRASH

Moves an existing, non-deleted email message to the trash. Trashed messages are recoverable and still count toward storage quota until purged. Prefer this over GMAIL_BATCH_DELETE_MESSAGES when recovery may be needed.

Input parameters

Name	Type	Required	Description
user_id	string	No	User’s email address or ‘me’ for the authenticated user.
message_id	string	Yes	Required. The unique identifier of the email message to move to trash. A hexadecimal string obtained from listing or fetching emails.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Patch Label

GMAIL_PATCH_LABEL

Patches the specified user-created label. System labels (e.g., INBOX, SENT, SPAM) cannot be modified and will be rejected.

Input parameters

Name	Type	Required	Description
id	string	Yes	The ID of the label to update.
name	string	No	The display name of the label. At least one of ‘name’, ‘messageListVisibility’, ‘labelListVisibility’, or ‘color’ must be provided.
color	object	No	The color to assign to the label. Must include both backgroundColor and textColor subfields; both values must come from Gmail’s predefined color palette.
userId	string	Yes	The user’s email address. The special value me can be used to indicate the authenticated user.
labelListVisibility	string	No	The visibility of the label in the label list in the Gmail web interface. Values: ‘labelShow’, ‘labelShowIfUnread’, ‘labelHide’.
messageListVisibility	string	No	The visibility of messages with this label in the message list. Values: ‘show’ or ‘hide’.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Patch send-as alias

GMAIL_PATCH_SEND_AS

Tool to patch the specified send-as alias for a Gmail user, updating properties such as display name, reply-to address, signature, default status, or SMTP configuration.

Input parameters

Name	Type	Required	Description
user_id	string	No	The user’s email address or the special value ‘me’ to indicate the authenticated user.
smtp_msa	object	No	Configuration for SMTP relay service.
signature	string	No	An optional HTML signature that is included in messages composed with this alias in the Gmail web UI. Added to new emails only.
is_default	boolean	No	Whether this address is selected as the default ‘From:’ address. Only true can be written to this field.
display_name	string	No	A name that appears in the ‘From:’ header for mail sent using this alias.
send_as_email	string	Yes	The send-as alias email address to update.
treat_as_alias	boolean	No	Whether Gmail should treat this address as an alias for the user’s primary email address.
reply_to_address	string	No	An optional email address that is included in a ‘Reply-To:’ header for mail sent using this alias.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Remove label (Deprecated)

GMAIL_REMOVE_LABEL

DEPRECATED: Use GMAIL_DELETE_LABEL instead. Permanently deletes a specific, existing user-created Gmail label by its ID; cannot delete system labels.

Input parameters

Name	Type	Required	Description
user_id	string	No	User’s email address or ‘me’ for the authenticated user.
label_id	string	Yes	ID of the user-created label to be permanently deleted; must exist and not be a system label.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Reply to email thread

GMAIL_REPLY_TO_THREAD

Sends a reply within a specific Gmail thread using the original thread’s subject. Do not provide a custom subject as it will start a new conversation instead of replying in-thread. Requires a valid thread_id and at least one of recipient_email, cc, or bcc.

Input parameters

Name	Type	Required	Description
cc	array	No	Carbon Copy (CC) recipients’ email addresses in format ‘user@domain.com’.
bcc	array	No	Blind Carbon Copy (BCC) recipients’ email addresses in format ‘user@domain.com’.
is_html	boolean	No	Indicates if message_body is HTML; if True, body must be valid HTML.
user_id	string	No	Identifier for the user sending the reply; ‘me’ refers to the authenticated user.
thread_id	string	Yes	Identifier of the Gmail thread for the reply. Must be a valid hexadecimal string, typically 15-16 characters long. Use GMAIL_LIST_THREADS or GMAIL_FETCH_EMAILS to retrieve valid thread IDs.
attachment	string	No	File(s) to attach to the reply. Requires name, mimetype, and s3key fields.
message_body	string	No	Content of the reply message, either plain text or HTML.
recipient_email	string	No	Primary recipient’s email address in format ‘user@domain.com’.
extra_recipients	array	No	Additional ‘To’ recipients. Should only be used if recipient_email is also provided.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Search People

GMAIL_SEARCH_PEOPLE

Searches contacts by matching the query against names, nicknames, emails, phone numbers, and organizations, optionally including ‘Other Contacts’. Only searches the authenticated user’s contact directory. Results paginate via next_page_token.

Input parameters

Name	Type	Required	Description
query	string	Yes	Matches contact names, nicknames, email addresses, phone numbers, and organization fields.
page_size	integer	No	Maximum results to return; values >30 are capped to 30 by the API.
person_fields	string	No	Comma-separated fields to return (e.g., ‘names,emailAddresses’). When ‘other_contacts’ is true, only ‘emailAddresses’, ‘metadata’, ‘names’, ‘phoneNumbers’ are allowed.
other_contacts	boolean	No	When True, searches both saved contacts and ‘Other Contacts’. When False, searches only saved contacts but allows all person_fields.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Send Draft

GMAIL_SEND_DRAFT

Sends an existing draft email AS-IS to recipients already defined within the draft. IMPORTANT: This action does NOT accept recipient parameters (to, cc, bcc). If the draft has no recipients, you must either create a new draft with recipients using GMAIL_CREATE_EMAIL_DRAFT, or use GMAIL_SEND_EMAIL. Send is immediate and irreversible.

Input parameters

Name	Type	Required	Description
user_id	string	No	The user’s email address. The special value me can be used to indicate the authenticated user.
draft_id	string	Yes	The ID of the draft to send. Use GMAIL_LIST_DRAFTS to retrieve valid draft IDs. The draft MUST already have recipients set — this action cannot add or override recipients.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Send Email

GMAIL_SEND_EMAIL

Sends an email via Gmail API using the authenticated user’s Google profile display name. Sends immediately and is irreversible. At least one of ‘to’/‘recipient_email’, ‘cc’, or ‘bcc’ must be provided. Gmail API limits total message size to ~25 MB after base64 encoding. To reply in an existing thread, use GMAIL_REPLY_TO_THREAD instead.

Input parameters

Name	Type	Required	Description
cc	array	No	Carbon Copy (CC) recipients’ email addresses.
bcc	array	No	Blind Carbon Copy (BCC) recipients’ email addresses.
body	string	No	Email content (plain text or HTML). If HTML, is_html must be True.
is_html	boolean	No	Set to True if the email body contains HTML tags.
subject	string	No	Subject line of the email.
user_id	string	No	User’s email address; the literal ‘me’ refers to the authenticated user.
attachment	string	No	File(s) to attach. IMPORTANT: mimetype MUST contain a ’/’ separator (e.g., ‘application/pdf’). Total message size must not exceed ~25 MB after base64 encoding.
from_email	string	No	Sender email address for the ‘From’ header. Use this to send from a verified alias configured in Gmail’s ‘Send mail as’ settings.
recipient_email	string	No	Primary recipient’s email address. You can also use ‘to’ as an alias for this parameter.
extra_recipients	array	No	Additional ‘To’ recipients (not Cc or Bcc). Should only be used if recipient_email is also provided.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Get IMAP Settings

GMAIL_SETTINGS_GET_IMAP

Retrieves the IMAP settings for a Gmail user account, including whether IMAP is enabled, auto-expunge behavior, expunge behavior, and maximum folder size.

Input parameters

Name	Type	Required	Description
user_id	string	No	The user’s email address or the special value ‘me’ to indicate the authenticated user.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Get POP settings

GMAIL_SETTINGS_GET_POP

Tool to retrieve POP settings for a Gmail account, including the current POP configuration such as access window and message disposition.

Input parameters

Name	Type	Required	Description
user_id	string	No	The user’s email address. The special value ‘me’ can be used to indicate the authenticated user.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Get send-as alias

GMAIL_SETTINGS_SEND_AS_GET

Tool to retrieve a specific send-as alias configuration for a Gmail user, including display name, signature, SMTP settings, and verification status. Fails with HTTP 404 if the specified address is not a member of the send-as collection.

Input parameters

Name	Type	Required	Description
user_id	string	No	The email address of the Gmail user whose send-as alias to retrieve, or the special value ‘me’ to indicate the authenticated user.
send_as_email	string	Yes	The send-as alias email address to retrieve. This is the email address that appears in the ‘From:’ header.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Stop watch notifications

GMAIL_STOP_WATCH

Tool to stop receiving push notifications for a Gmail mailbox. Use when you need to disable watch notifications previously set up via the watch endpoint.

Input parameters

Name	Type	Required	Description
user_id	string	No	The user’s email address. The special value ‘me’ can be used to indicate the authenticated user.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Untrash Message

GMAIL_UNTRASH_MESSAGE

Tool to remove a message from trash in Gmail. Use when you need to restore a previously trashed email message.

Input parameters

Name	Type	Required	Description
user_id	string	No	User’s email address or ‘me’ for the authenticated user.
message_id	string	Yes	Required. The unique identifier of the email message to remove from trash. A hexadecimal string obtained from listing or fetching emails.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Untrash thread

GMAIL_UNTRASH_THREAD

Tool to remove a thread from trash in Gmail. Use when you need to restore a deleted thread and its messages.

Input parameters

Name	Type	Required	Description
user_id	string	No	The user’s email address. The special value ‘me’ can be used to indicate the authenticated user.
thread_id	string	Yes	The ID of the thread to remove from trash.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Update draft

GMAIL_UPDATE_DRAFT

Updates (replaces) an existing Gmail draft’s content in-place by draft ID. This action replaces the entire draft content with the new message — it does not patch individual fields. Provide complete draft content to avoid data loss.

Input parameters

Name	Type	Required	Description
cc	array	No	Carbon Copy (CC) recipients’ email addresses. Each must be a valid email address or display name format.
bcc	array	No	Blind Carbon Copy (BCC) recipients’ email addresses. Each must be a valid email address or display name format.
body	string	No	Email body content (plain text or HTML); is_html must be True if HTML. Can also be provided as ‘message_body’.
is_html	boolean	No	Set to True if body is already formatted HTML.
subject	string	No	Email subject line.
user_id	string	No	User’s email address or ‘me’ for the authenticated user.
draft_id	string	Yes	The ID of the draft to update. Must be a valid draft ID from GMAIL_LIST_DRAFTS or GMAIL_CREATE_EMAIL_DRAFT.
thread_id	string	No	ID of an existing Gmail thread. If provided, the draft will be part of this thread.
attachment	string	No	File(s) to attach to the draft. Replaces any existing attachments.
recipient_email	string	No	Primary recipient’s email address.
extra_recipients	array	No	Additional ‘To’ recipients. Should only be used if recipient_email is also provided.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Update IMAP settings

GMAIL_UPDATE_IMAP_SETTINGS

Tool to update IMAP settings for a Gmail account, such as enabling/disabling IMAP, setting auto-expunge behavior, or configuring folder size limits.

Input parameters

Name	Type	Required	Description
enabled	boolean	No	Whether IMAP is enabled for the account.
user_id	string	No	The user’s email address. The special value ‘me’ can be used to indicate the authenticated user.
autoExpunge	boolean	No	If this value is true, Gmail will immediately expunge a message when it is marked as deleted in IMAP.
maxFolderSize	integer	No	An optional limit on the number of messages that an IMAP folder may contain. Legal values are 0, 1000, 2000, 5000 or 10000. A value of zero means no limit.
expungeBehavior	string	No	The action that will be executed on a message when it is marked as deleted and expunged from the last visible IMAP folder. Values: ‘expungeBehaviorUnspecified’, ‘archive’, ‘trash’, ‘deleteForever’.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Update Label

GMAIL_UPDATE_LABEL

Tool to update the properties of an existing Gmail label, including name, visibility settings, or color.

Input parameters

Name	Type	Required	Description
id	string	Yes	The ID of the label to update.
name	string	No	The display name of the label.
color	object	No	Color settings for the label. Both backgroundColor and textColor must be provided together.
userId	string	No	The user’s email address. The special value me can be used to indicate the authenticated user.
labelListVisibility	string	No	Visibility of the label in the label list (Gmail sidebar).
messageListVisibility	string	No	Visibility of messages with this label in the message list.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Update Language Settings

GMAIL_UPDATE_LANGUAGE_SETTINGS

Tool to update the language settings for a Gmail user. The returned displayLanguage may differ from the requested value if Gmail selects a close variant.

Input parameters

Name	Type	Required	Description
user_id	string	No	The email address of the Gmail user whose language settings are to be updated, or the special value ‘me’ to indicate the currently authenticated user.
display_language	string	Yes	The language to display Gmail in, formatted as an RFC 3066 Language Tag (e.g., ‘en-GB’ for British English, ‘fr’ for French, ‘ja’ for Japanese, ‘es’ for Spanish).

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Update POP settings

GMAIL_UPDATE_POP_SETTINGS

Tool to update POP settings for a Gmail account, configuring POP access window or message disposition behavior.

Input parameters

Name	Type	Required	Description
user_id	string	No	The user’s email address. The special value ‘me’ can be used to indicate the authenticated user.
disposition	string	No	The action that will be executed on a message after it has been fetched via POP. Values: ‘dispositionUnspecified’, ‘leaveInInbox’, ‘archive’, ‘trash’, ‘markRead’.
access_window	string	No	The range of messages which are accessible via POP. Values: ‘accessWindowUnspecified’, ‘disabled’, ‘fromNowOn’, ‘allMail’.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Update send-as alias

GMAIL_UPDATE_SEND_AS

Tool to update a send-as alias for a Gmail user, modifying display name, signature, reply-to address, or SMTP settings. Gmail sanitizes HTML signatures before saving. Addresses other than the primary can only be updated by service accounts with domain-wide authority.

Input parameters

Name	Type	Required	Description
user_id	string	No	The email address of the Gmail user whose send-as alias to update, or the special value ‘me’ to indicate the authenticated user.
smtp_msa	object	No	SMTP relay configuration for the send-as alias.
signature	string	No	Optional HTML signature for messages composed with this alias in Gmail web UI. Gmail sanitizes HTML before saving.
is_default	boolean	No	Set to true to make this the default ‘From:’ address. Setting true makes the previous default false. Only legal writable value is true.
display_name	string	No	Name to appear in ‘From:’ header.
send_as_email	string	Yes	The send-as alias email address to update. This is the email address that appears in the ‘From:’ header.
treat_as_alias	boolean	No	Whether Gmail treats this address as an alias for the user’s primary email.
reply_to_address	string	No	Optional email address for ‘Reply-To:’ header. Gmail omits header if empty.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Update User Attributes Values

GMAIL_UPDATE_USER_ATTRIBUTES_VALUES

Update user attribute values for a resource. Use this action to set or update custom attributes for a user within an organization or project. When setting a value for an attribute key that also exists in SAML, the Sanity value will take precedence and shadow the SAML value.

Input parameters

Name	Type	Required	Description
userId	string	Yes	The unique identifier of the user whose attributes to update.
attributes	object	Yes	A dictionary of attribute key-value pairs to set for the user. Values can be strings, numbers, booleans, arrays, or nested objects.
resourceId	string	Yes	The unique identifier of the resource. For organizations, this is the organization ID.
resourceType	string	Yes	The type of resource that scopes the user attributes. Values: ‘organization’ or ‘project’.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Update Vacation Settings

GMAIL_UPDATE_VACATION_SETTINGS

Tool to update vacation responder settings for a Gmail user, configuring out-of-office auto-replies.

Input parameters

Name	Type	Required	Description
userId	string	No	The user’s email address. The special value ‘me’ can be used to indicate the authenticated user.
endTime	string	No	An optional end time for sending auto-replies (epoch ms).
startTime	string	No	An optional start time for sending auto-replies (epoch ms).
enableAutoReply	boolean	No	Flag that controls whether Gmail automatically replies to messages.
responseSubject	string	No	Optional text to prepend to the subject line in vacation responses.
responseBodyHtml	string	No	Response body in HTML format. Gmail will sanitize the HTML before storing it.
restrictToDomain	boolean	No	Flag that determines whether responses are sent to recipients outside of the user’s domain. This feature is only available for Google Workspace users.
restrictToContacts	boolean	No	Flag that determines whether responses are sent to recipients who are not in the user’s list of contacts.
responseBodyPlainText	string	No	Response body in plain text format. If both responseBodyPlainText and responseBodyHtml are specified, responseBodyHtml will be used.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.