Skip to main content
Gmail logo
  • Category: email
  • Auth: OAUTH2
  • Composio-managed OAuth available? Yes
  • Tools: 63
  • Triggers: 2
  • Slug: GMAIL
  • Version: 20261103_00

Frequently Asked Questions

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.
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. See How to create OAuth2 credentials for Google Apps.
When using custom OAuth credentials, the Gmail API must be enabled in the Google Cloud project that owns those credentials. Enable it in Google Cloud Console under APIs & Services, wait a few minutes, and retry.
The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the Google OAuth scopes docs. If you’re creating auth configs programmatically, see the programmatic auth config guide.
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.
Gmail triggers poll roughly every minute by default. If you need lower latency, consider using webhooks or Google Pub/Sub integrations.
Google enforces per-minute and daily request quotas. If you’re using Composio’s default OAuth app, you share that quota with other users, which can cause limits to be hit faster. Use your own OAuth app credentials to get a dedicated quota, and add exponential backoff and retries to handle transient rate limits.
Use a session so your agent discovers the email tool at runtime instead of hard-coding an action slug.
  1. Connect Gmail for your user, then create a session for the same user and give your agent the session tools.
  2. Upload ./report.pdf to that session with the experimental session.experimental.files API. See sandbox files and mounts for Python, TypeScript, and API examples. The agent can read the uploaded file in the remote sandbox, not from your application’s local filesystem.
  3. Ask the agent to send the email with your recipient, subject, body, and the uploaded file’s sandbox path. For a file mounted at /mnt/files/report.pdf, instruct it to use the sandbox’s get_mount_file_s3_key("report.pdf") helper and pass the returned key to the discovered email tool in a file object with name, mimetype, and s3key. A sandbox path is not a storage key. See session files and toolkit attachments.
  4. Check the tool result before reporting that the email was sent. If the tool fails, report the error.
Automatic file upload is off by default. This workflow uploads the file explicitly and does not require enabling automatic file handling. The session files API is experimental and may change.
If a user on Composio-managed Gmail auth hits Google’s “app is blocked” / unverified-app screen after adding gmail.settings.basic, use your own Google OAuth app verified for https://www.googleapis.com/auth/gmail.settings.basic, then reconnect.
Use https://www.googleapis.com/auth/gmail.metadata only when the app needs message metadata such as labels and headers, not message bodies or payload content. Gmail treats gmail.metadata as a restricted metadata-only scope, and it is not compatible with broader content-access scopes such as gmail.readonly, gmail.modify, or mail.google.com in the same OAuth request.If a tool needs full email content, remove gmail.metadata from the auth config and request a Gmail scope that allows message content access. Then reconnect the account so the new scope set is granted.

Tools

Slug: GMAIL_ADD_LABEL_TO_EMAILAdds 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

string
User’s email address or ‘me’ for the authenticated user.
string
required
Immutable ID of the message to modify. Gmail message IDs are hexadecimal strings (e.g., ‘1a2b3c4d5e6f7890’). IMPORTANT: Do NOT use UUIDs (32-character strings like ‘093ca4662b214d5eba8f4ceeaad63433’), thread IDs, or internal system IDs - these will cause ‘Invalid id value’ errors. Obtain valid message IDs from: (1) ‘GMAIL_FETCH_EMAILS’ response ‘messageId’ field, (2) ‘GMAIL_FETCH_MESSAGE_BY_THREAD_ID’ response, or (3) ‘GMAIL_LIST_THREADS’ and then fetching thread messages.
array
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. Use full CATEGORY_ prefix (e.g., ‘CATEGORY_UPDATES’ not ‘UPDATES’). Custom labels: call ‘listLabels’ first to get the ID (format: ‘Label_<number>’). Do NOT use the label display name; the API requires the ID. SENT, DRAFT, CHAT are immutable and cannot be added or removed. A label cannot appear in both add_label_ids and remove_label_ids.
array
Label IDs to remove (IDs, not display names). System labels: INBOX, SPAM, TRASH, UNREAD, STARRED, IMPORTANT, CATEGORY_PERSONAL, CATEGORY_SOCIAL, CATEGORY_PROMOTIONS, CATEGORY_UPDATES, CATEGORY_FORUMS. Use full CATEGORY_ prefix (e.g., ‘CATEGORY_UPDATES’ not ‘UPDATES’). Custom labels: call ‘listLabels’ first to get the ID (format: ‘Label_<number>’). SENT, DRAFT, CHAT are immutable and cannot be removed. Common operations: to mark as read, remove ‘UNREAD’; to archive, remove ‘INBOX’. A label cannot appear in both add_label_ids and remove_label_ids.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_BATCH_DELETE_MESSAGESPermanently deletes multiple Gmail messages by ID, bypassing Trash. A successful request does not confirm individual messages existed or were deleted.

Input Parameters

string
User’s email address or ‘me’ for the authenticated user.
array
required
List of Gmail message IDs to delete. Each ID must be a hexadecimal string (e.g., ‘18c5f5d1a2b3c4d5’). Obtain IDs from actions like GMAIL_FETCH_EMAILS or GMAIL_LIST_THREADS - do not use human-readable descriptions.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_BATCH_MODIFY_MESSAGESAdds or removes labels on up to 1,000 Gmail messages in one request, supporting operations such as archiving and marking messages read or unread. A successful response confirms request acceptance, not individual message status.

Input Parameters

string
User’s email address or ‘me’ for the authenticated user.
array
required
List of message IDs to modify. Maximum 1,000 message IDs per request. Get message IDs from GMAIL_FETCH_EMAILS or GMAIL_LIST_THREADS actions. Accepts ‘messageIds’, ‘ids’, or ‘message_ids’ as the parameter name.
array
List of label IDs to add to the messages. IMPORTANT: Use label IDs, NOT label display names. System labels use their name as ID: INBOX, STARRED, IMPORTANT, SENT, DRAFT, SPAM, TRASH, UNREAD, CATEGORY_PERSONAL, CATEGORY_SOCIAL, CATEGORY_PROMOTIONS, CATEGORY_UPDATES, CATEGORY_FORUMS. Custom labels MUST use their ID (format: ‘Label_XXX’, e.g., ‘Label_1’, ‘Label_25’), NOT the display name (e.g., do NOT use ‘Work’ or ‘Projects’). Call GMAIL_LIST_LABELS first to get the ‘id’ field for custom labels. At least one of add_label_ids or remove_label_ids must be provided. CONSTRAINT: Label IDs must NOT overlap with remove_label_ids - cannot add and remove the same label.
array
List of label IDs to remove from the messages. IMPORTANT: Use label IDs, NOT label display names. System labels use their name as ID: INBOX, STARRED, IMPORTANT, SENT, SPAM, TRASH, UNREAD. Custom labels MUST use their ID (format: ‘Label_XXX’, e.g., ‘Label_1’, ‘Label_25’), NOT the display name (e.g., do NOT use ‘Work’ or ‘Projects’). Call GMAIL_LIST_LABELS first to get the ‘id’ field for custom labels. Common use cases: Remove ‘UNREAD’ to mark as read, remove ‘INBOX’ to archive. Note: ‘DRAFT’ cannot be removed - use GMAIL_DELETE_DRAFT instead. At least one of add_label_ids or remove_label_ids must be provided. CONSTRAINT: Label IDs must NOT overlap with add_label_ids - cannot add and remove the same label.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_CREATE_EMAIL_DRAFTCreates a Gmail draft with optional recipients, subject, plain or HTML body, attachments, and threading. When a requested thread cannot be fetched, the draft is created without threading; a provided subject is used instead of the thread subject.

Input Parameters

array
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>’). Plain names without email addresses are NOT valid. Optional for drafts (recipients can be added later before sending).
array
Blind Carbon Copy (BCC) recipients’ email addresses. Each must be a valid email address (e.g., ‘user@example.com’) or display name format (e.g., ‘Bob Jones <user@example.com>’). Plain names without email addresses are NOT valid. Optional for drafts (recipients can be added later before sending).
string
Email body content (plain text or HTML); is_html must be True if HTML. Optional - drafts can be created without a body and edited later before sending. Can also be provided as ‘message_body’.
boolean
Set to True if body is already formatted HTML. When False, plain text newlines are auto-converted to
tags. Both modes result in HTML email; this flag controls whether the body content is treated as raw HTML or plain text that gets HTML formatting applied.
string
Email subject line. Optional - drafts can be created without a subject and edited later before sending. When creating a draft reply to an existing thread (thread_id provided), leave this empty to stay in the same thread. Setting a subject will create a NEW thread instead.
string
User’s email address or ‘me’ for the authenticated user.
string
ID of an existing Gmail thread to reply to; omit for new thread. If the thread ID is invalid or inaccessible, the draft will be created as a new thread instead of failing.
string
File(s) to attach to the email. Accepts a single file or a list of files. Total message size including base64-encoded attachments must be under 25 MB; use shareable links (e.g., Google Drive) for larger files.
string
Primary recipient’s email address. Must be a valid email address (e.g., ‘user@example.com’) or display name format (e.g., ‘John Doe <user@example.com>’). A plain name without an email address (e.g., ‘John Doe’) is NOT valid - the ’@’ symbol and domain are required. Optional for drafts (recipients can be added later before sending). Use extra_recipients if you want to send to multiple recipients.
array
Additional ‘To’ recipients’ email addresses (not Cc or Bcc). Each must be a valid email address (e.g., ‘user@example.com’), display name format (e.g., ‘Jane Doe <user@example.com>’), or ‘me’ for the authenticated user. Plain names without email addresses are NOT valid. Should only be used if recipient_email is also provided.
boolean
Append the sender’s Gmail signature (the ‘Send mail as’ signature configured in Gmail settings) to the message body, ahead of any quoted or forwarded content. Skipped when the body already ends with that signature, when no signature is configured, or when the connection lacks permission to read Gmail settings. Set to false to send the body exactly as provided.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_CREATE_FILTERTool 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

object
required
REQUIRED. Action that the filter will perform on messages matching the criteria. At least one action field must be specified.
string
The user’s email address or the special value ‘me’ to indicate the authenticated user for whom the filter will be created.
object
required
REQUIRED. Message matching criteria that determines which messages the filter will apply to. At least one criteria field must be specified.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_CREATE_LABELCreates a Gmail label and returns its label ID. For nested labels, it may create missing parent labels; on a name conflict it attempts to return the existing matching label.

Input Parameters

string
The email address of the user in whose account the label will be created.
string
required
REQUIRED. The name for the new label. Must be unique within the account, non-blank, maximum length 225 characters, cannot contain commas (’,’), not only whitespace, and must not be a reserved system label. Reserved English system labels include: Inbox, Starred, Important, Sent, Draft, Drafts, Spam, Trash, etc. Forward slashes (’/’) are allowed and used to create hierarchical nested labels (e.g., ‘Work/Projects’, ‘Personal/Finance’). When creating nested labels, any missing parent labels will be automatically created (similar to ‘mkdir -p’). Periods (’.’) are allowed and commonly used for numbering schemes (e.g., ‘1. Action Items’, ‘2. Projects’). Note: ‘name’ is also accepted as an alias for this field. If a label with this name already exists, returns a 409 conflict; use GMAIL_LIST_LABELS to check existing labels and reuse the existing labelId, or use GMAIL_PATCH_LABEL to update it.
string ("#000000" | "#434343" | "#666666" | "#999999" | "#cccccc" | "#efefef" | "#f3f3f3" | "#ffffff" | "#fb4c2f" | "#ffad47" | "#fad165" | "#16a766" | "#43d692" | "#4a86e8" | "#a479e2" | "#f691b3" | "#f6c5be" | "#ffe6c7" | "#fef1d1" | "#b9e4d0" | "#c6f3de" | "#c9daf8" | "#e4d7f5" | "#fcdee8" | "#efa093" | "#ffd6a2" | "#fce8b3" | "#89d3b2" | "#a0eac9" | "#a4c2f4" | "#d0bcf1" | "#fbc8d9" | "#e66550" | "#ffbc6b" | "#fcda83" | "#44b984" | "#68dfa9" | "#6d9eeb" | "#b694e8" | "#f7a7c0" | "#cc3a21" | "#eaa041" | "#f2c960" | "#149e60" | "#3dc789" | "#3c78d8" | "#8e63ce" | "#e07798" | "#ac2b16" | "#cf8933" | "#d5ae49" | "#0b804b" | "#2a9c68" | "#285bac" | "#653e9b" | "#b65775" | "#464646" | "#e7e7e7" | "#0d3472" | "#b6cff5" | "#0d3b44" | "#98d7e4" | "#3d188e" | "#e3d7ff" | "#711a36" | "#fbd3e0" | "#8a1c0a" | "#f2b2a8" | "#7a2e0b" | "#ffc8af" | "#7a4706" | "#ffdeb5" | "#594c05" | "#fbe983" | "#684e07" | "#fdedc1" | "#0b4f30" | "#b3efd3" | "#04502e" | "#a2dcc1" | "#c2c2c2" | "#4986e7" | "#2da2bb" | "#b99aff" | "#994a64" | "#f691b2" | "#ff7537" | "#ffad46" | "#662e37" | "#cca6ac" | "#094228" | "#42d692" | "#076239" | "#16a765" | "#1a764d" | "#1c4587" | "#41236d" | "#822111" | "#83334c" | "#a46a21" | "#aa8831" | "#ebdbde")
Text color for the label. Gmail only accepts colors from a predefined palette of 102 specific hex values. Common color names like ‘YELLOW’, ‘RED’, ‘BLUE’, ‘GREEN’, ‘ORANGE’, ‘PURPLE’, ‘PINK’ are automatically mapped to the closest Gmail palette color. Provide either a common color name, a Gmail palette color name (e.g., ‘BLACK’, ‘ROYAL_BLUE’), or exact hex value (e.g., ‘#000000’, ‘#4a86e8’). If only text_color is provided without background_color, a complementary background color (white or black) will be auto-selected for optimal contrast. Full palette: https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.labels#Color Must be supplied together with background_color — providing only one will cause a 400 error. The auto-selected complementary color behavior does not apply; both colors are required.
string ("#000000" | "#434343" | "#666666" | "#999999" | "#cccccc" | "#efefef" | "#f3f3f3" | "#ffffff" | "#fb4c2f" | "#ffad47" | "#fad165" | "#16a766" | "#43d692" | "#4a86e8" | "#a479e2" | "#f691b3" | "#f6c5be" | "#ffe6c7" | "#fef1d1" | "#b9e4d0" | "#c6f3de" | "#c9daf8" | "#e4d7f5" | "#fcdee8" | "#efa093" | "#ffd6a2" | "#fce8b3" | "#89d3b2" | "#a0eac9" | "#a4c2f4" | "#d0bcf1" | "#fbc8d9" | "#e66550" | "#ffbc6b" | "#fcda83" | "#44b984" | "#68dfa9" | "#6d9eeb" | "#b694e8" | "#f7a7c0" | "#cc3a21" | "#eaa041" | "#f2c960" | "#149e60" | "#3dc789" | "#3c78d8" | "#8e63ce" | "#e07798" | "#ac2b16" | "#cf8933" | "#d5ae49" | "#0b804b" | "#2a9c68" | "#285bac" | "#653e9b" | "#b65775" | "#464646" | "#e7e7e7" | "#0d3472" | "#b6cff5" | "#0d3b44" | "#98d7e4" | "#3d188e" | "#e3d7ff" | "#711a36" | "#fbd3e0" | "#8a1c0a" | "#f2b2a8" | "#7a2e0b" | "#ffc8af" | "#7a4706" | "#ffdeb5" | "#594c05" | "#fbe983" | "#684e07" | "#fdedc1" | "#0b4f30" | "#b3efd3" | "#04502e" | "#a2dcc1" | "#c2c2c2" | "#4986e7" | "#2da2bb" | "#b99aff" | "#994a64" | "#f691b2" | "#ff7537" | "#ffad46" | "#662e37" | "#cca6ac" | "#094228" | "#42d692" | "#076239" | "#16a765" | "#1a764d" | "#1c4587" | "#41236d" | "#822111" | "#83334c" | "#a46a21" | "#aa8831" | "#ebdbde")
Background color for the label. Gmail only accepts colors from a predefined palette of 102 specific hex values. Common color names like ‘YELLOW’, ‘RED’, ‘BLUE’, ‘GREEN’, ‘ORANGE’, ‘PURPLE’, ‘PINK’ are automatically mapped to the closest Gmail palette color. Provide either a common color name, a Gmail palette color name (e.g., ‘ROYAL_BLUE’, ‘CARIBBEAN_GREEN’), or exact hex value (e.g., ‘#4a86e8’, ‘#43d692’). If only background_color is provided without text_color, a complementary text color (white or black) will be auto-selected for optimal contrast. Full palette: https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.labels#Color Must be supplied together with text_color — providing only one will cause a 400 error. The auto-selected complementary color behavior does not apply; both colors are required.
string ("labelShow" | "labelShowIfUnread" | "labelHide")
Controls how the label is displayed in the label list in the Gmail sidebar. Valid values: ‘labelShow’ (always show), ‘labelShowIfUnread’ (show only if unread messages), ‘labelHide’ (hide from list).
string ("show" | "hide")
Controls how messages with this label are displayed in the message list. Valid values: ‘show’ or ‘hide’. Note: These values are different from label_list_visibility - do NOT use ‘labelShow’ or ‘labelHide’ here.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_DELETE_DRAFTPermanently deletes a specific Gmail draft using its ID with no recovery possible; verify the correct draft_id and obtain explicit user confirmation before calling. Ensure the draft exists and the user has necessary permissions for the given user_id.

Input Parameters

string
User’s email address or ‘me’ for the authenticated user; ‘me’ is recommended.
string
required
Immutable ID of the draft to delete. Must be obtained from GMAIL_LIST_DRAFTS or GMAIL_CREATE_EMAIL_DRAFT actions. Draft IDs typically have an ‘r’ prefix (e.g., ‘r-1234567890’ or ‘r1234567890’). Draft IDs differ from message IDs used in GMAIL_BATCH_DELETE_MESSAGES — do not interchange. When multiple similar drafts exist, confirm the exact ID via GMAIL_LIST_DRAFTS before deleting.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_DELETE_FILTERTool to permanently delete a Gmail filter by its ID. Use when you need to remove an existing email filtering rule.

Input Parameters

string
User’s email address or ‘me’ for the authenticated user.
string
required
The ID of the filter to be deleted. Filter IDs can be obtained from GMAIL_LIST_FILTERS action.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_DELETE_LABELPermanently 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 action instead.

Input Parameters

string
User’s email address or ‘me’ for the authenticated user.
string
required
ID of the user-created label to be permanently DELETED from the account. Must be a custom label ID (format: ‘Label_<id>’ e.g., ‘Label_1’, ‘Label_42’). System labels (INBOX, SENT, DRAFT, UNREAD, STARRED, IMPORTANT, SPAM, TRASH, CATEGORY_*, etc.) cannot be deleted. WARNING: This action permanently DELETES the label definition from your account - it does NOT remove a label from a message. To add/remove labels from messages, use GMAIL_ADD_LABEL_TO_EMAIL instead.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_DELETE_MESSAGEPermanently 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

string
User’s email address. The special value ‘me’ refers to the authenticated user.
string
required
Identifier of the email message to delete.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_DELETE_THREADTool 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

string
required
ID of the Thread to delete.
string
User’s email address. The special value ‘me’ refers to the authenticated user.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_FETCH_EMAILSLists Gmail messages with query and label filtering, pagination, and optional message details. Individual detail fetches returning 404, 429, or 503 are skipped, so a page can contain fewer messages than the list result.

Input Parameters

string
Gmail advanced search query (e.g., ‘from:user subject:meeting’). Supported operators: ‘from:’, ‘to:’, ‘subject:’, ‘label:’, ‘has:’, ‘is:’, ‘in:’, ‘category:’, ‘after:YYYY/MM/DD’, ‘before:YYYY/MM/DD’, AND/OR/NOT. IMPORTANT - ‘is:’ vs ‘label:’ usage: Use ‘is:’ for special mail states: is:snoozed, is:unread, is:read, is:starred, is:important. Use ‘label:’ ONLY for user-created labels (e.g., ‘label:work’, ‘label:projects’). Note: ‘muted’ may work with both ‘is:muted’ and ‘label:muted’ based on community reports. Common mistake: ‘label:snoozed’ is WRONG - use ‘is:snoozed’ instead. Use quotes for exact phrases. Omit for no query filter. after:/before: evaluate whole calendar days in UTC; before: is exclusive — adjust for local timezone to avoid off-by-one-day gaps.
string
User’s email address or ‘me’ for the authenticated user. Non-‘me’ addresses require domain-level delegation; without it, authentication or not-found errors result.
boolean
If false, uses optimized concurrent metadata fetching for faster performance (~75% improvement). If true, uses standard detailed message fetching. When false, only essential fields (subject, sender, recipient, time, labels) are guaranteed. Body content and attachment details require verbose=true even when include_payload=true.
boolean
If true, only returns message IDs from the list API without fetching individual message details. Fastest option for getting just message IDs and thread IDs.
array
Filter by label IDs; only messages with all specified labels are returned (AND logic). Optional - omit or use empty list to fetch all messages without label filtering. System label IDs: ‘INBOX’, ‘SPAM’, ‘TRASH’, ‘UNREAD’, ‘STARRED’, ‘IMPORTANT’, ‘CATEGORY_PRIMARY’ (alias ‘CATEGORY_PERSONAL’), ‘CATEGORY_SOCIAL’, ‘CATEGORY_PROMOTIONS’, ‘CATEGORY_UPDATES’, ‘CATEGORY_FORUMS’. For custom/user-created labels, you MUST use the label ID (e.g., ‘Label_123456’), NOT the display name. Use the ‘listLabels’ action to find label IDs for custom labels. Combining label_ids with label: in query applies AND logic across both, which can silently over-restrict results; use one strategy consistently.
string
Token for retrieving a specific page, obtained from a previous response’s nextPageToken. Must be a valid opaque token string from a previous API response. Do not pass arbitrary values. Omit for the first page. Loop calls using nextPageToken until it is absent to avoid silently missing messages. resultSizeEstimate is approximate — do not use as a stopping condition.
integer
Maximum number of messages to retrieve per page. Default of 1 retrieves only a single message; set higher for practical use. Hard cap is 500 per page.
boolean
Set to true to include full message payload (headers, body, attachments); false for metadata only. payload may still be null even when true; use GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID for guaranteed complete content. When payload is present, bodies are base64url-encoded in payload.parts; replace ’-’→’+’ and ’_’→’/’ and fix padding before decoding, and check both text/plain and text/html parts.
boolean
Set to true to include messages from ‘SPAM’ and ‘TRASH’.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_FETCH_MESSAGE_BY_MESSAGE_IDFetches a Gmail message by its message ID in the requested format and returns formatted message details. Available fields depend on the format.

Input Parameters

string
Format for message content. ‘minimal’: lightest (ID, thread ID, labels only). ‘metadata’: headers and message metadata without body content - ideal for summarization, analysis, or when you only need subject/sender/timestamp (recommended for most use cases). ‘full’: complete MIME structure with 50+ headers, nested parts, and base64url-encoded body data - heavy payload, only use when you need the complete raw MIME structure for parsing attachments or body content. ‘raw’: entire RFC 2822 formatted message as base64url string.
string
User’s email address or ‘me’ for the authenticated user.
string
required
The Gmail API message ID (hexadecimal string, typically 15-16 characters like ‘19b11732c1b578fd’). Must be obtained from Gmail API responses (e.g., List Messages, Search Messages). Do NOT use email subjects, dates, sender names, or custom identifiers. Do NOT use threadId (use GMAIL_FETCH_MESSAGE_BY_THREAD_ID for threads), the Message-ID email header, or any fabricated value — only IDs from Gmail API list/search responses.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_FETCH_MESSAGE_BY_THREAD_IDRetrieves messages from an accessible Gmail thread by thread ID, returning thread details and a messages array. Message order is not guaranteed; use messageTimestamp to identify oldest or newest messages and labelIds to filter drafts.

Input Parameters

string
The email address of the user.
string
required
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. Legacy Gmail web UI IDs (e.g., ‘FMfcgzQfBZdVqKZcSVBhqwWLKWCtDdWQ’) are NOT supported - use the API thread ID instead. Deduplicate thread_ids before calling when multiple listed messages share the same threadId to avoid redundant calls.
string
Opaque page token for fetching a specific page of messages if results are paginated. Iterate calls by passing the returned nextPageToken until it is absent; stopping early will miss messages in long threads.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_FORWARD_MESSAGEForwards an existing Gmail message to specified recipients, with optional additional text. The tool copies original message parts into a new message, but may alter MIME structure and attachment metadata.

Input Parameters

array
List of email addresses to CC.
array
List of email addresses to BCC.
string
User’s email address or ‘me’ for the authenticated user.
string
required
Gmail message ID (hexadecimal string, e.g., ‘17f45ec49a9c3f1b’). Must contain only hex characters [0-9a-fA-F]. Obtain this from actions like ‘List Messages’ or ‘Fetch Emails’.
array
required
List of email addresses to forward the message to.
string
Optional additional text to include before the forwarded content.
boolean
Append the sender’s Gmail signature (the ‘Send mail as’ signature configured in Gmail settings) to the message body, ahead of any quoted or forwarded content. Skipped when the body already ends with that signature, when no signature is configured, or when the connection lacks permission to read Gmail settings. Set to false to send the body exactly as provided.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_GET_ATTACHMENTRetrieves a Gmail message attachment by message and attachment IDs and returns a downloadable file using the supplied filename.

Input Parameters

string
User’s email address (‘me’ for authenticated user).
string
required
Desired filename for the downloaded attachment. This is a required string field - do not pass null.
string
required
Immutable ID of the message containing the attachment. This is a required string field - do not pass null. Obtain the message_id from Gmail API responses (e.g., fetchEmails, listThreads).
string
required
The internal Gmail attachment ID (NOT the filename). This is a system-generated token string like ‘ANGjdJ8s…’. Obtain this ID from the ‘attachmentId’ field in the ‘attachmentList’ array returned by fetchEmails or fetchMessageByMessageId actions. Do NOT pass the filename (e.g., ‘report.pdf’). Requires a fully hydrated message payload: call GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID with format=‘full’ to obtain valid attachment IDs — lightweight fetch modes may omit attachmentList entirely.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_GET_AUTO_FORWARDINGTool to get the auto-forwarding setting for the specified account. Use when you need to retrieve the current auto-forwarding configuration including enabled status, forwarding email address, and message disposition.

Input Parameters

string
The user’s email address. The special value ‘me’ can be used to indicate the authenticated user.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_GET_CONTACTSLists saved Google contacts with selectable fields and pagination, optionally including Other Contacts. Other Contacts are fetched on the first page; endpoint failures can result in partial results, and contact records may be sparse.

Input Parameters

string
Token to retrieve a specific page of results, obtained from ‘nextPageToken’ in a previous response. Repeat calls with each successive nextPageToken until it is absent — stopping early silently omits contacts.
string
Comma-separated person fields to retrieve for each contact (e.g., ‘names,emailAddresses’).
string
Identifier for the person resource whose connections are listed; use ‘people/me’ for the authenticated user.
boolean
Include ‘Other Contacts’ (interacted with but not explicitly saved) in addition to regular contacts. WARNING: ‘Other Contacts’ often have incomplete data - they may lack names, phone numbers, and other fields even when requested. These auto-generated contacts are created from email interactions and typically only have email addresses. Set to False if you need contacts with complete name information. When True, each contact will have a ‘contactSource’ field indicating its origin. When True, person_fields is restricted to emailAddresses, names, phoneNumbers, and metadata only — requesting other fields (e.g., organizations, birthdays) causes validation errors or silent omissions.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_GET_DRAFTRetrieves a single Gmail draft by its ID. Use this to fetch and inspect draft content before sending via GMAIL_SEND_DRAFT. The format parameter controls the level of detail returned.

Input Parameters

string
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).
string
The user’s email address. The special value me can be used to indicate the authenticated user.
string
required
The ID of the draft to retrieve. Draft IDs are typically alphanumeric strings (e.g., ‘r99885592323229922’). Use GMAIL_LIST_DRAFTS to retrieve valid draft IDs.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_GET_FILTERTool 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

string
required
The ID of the filter to be fetched.
string
The user’s email address or the special value ‘me’ to indicate the authenticated user.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_GET_LABELGets details for a specified Gmail label. Use this to retrieve label information including name, type, visibility settings, message/thread counts, and color.

Input Parameters

string
required
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).
string
The user’s email address. The special value ‘me’ can be used to indicate the authenticated user.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_GET_LANGUAGE_SETTINGSTool to retrieve the language settings for a Gmail user. Use when you need to determine the display language preference for the authenticated user or a specific Gmail account.

Input Parameters

string
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

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_GET_PEOPLERetrieves a person’s details by resource name or lists the authenticated user’s Other Contacts, using a field mask to select the information returned. Other Contacts can be paginated and queried using a sync token for changes since a previous sync.

Input Parameters

array
Source types to include when retrieving other contacts. READ_SOURCE_TYPE_CONTACT supports basic fields (emailAddresses, metadata, names, phoneNumbers, photos). READ_SOURCE_TYPE_PROFILE supports extended fields (birthdays, genders, organizations, etc.) but requires READ_SOURCE_TYPE_CONTACT to also be included. Applicable only when other_contacts is true.
integer
The number of ‘Other Contacts’ to return per page. Applicable only when other_contacts is true.
string
An opaque token from a previous response to retrieve the next page of ‘Other Contacts’ results. Applicable only when other_contacts is true and paginating.
string
A token from a previous ‘Other Contacts’ list call to retrieve only changes since the last sync; leave empty for an initial full sync. Applicable only when other_contacts is true.
string
A comma-separated field mask to restrict which fields on the person (or persons) are returned. Consult the Google People API documentation for a comprehensive list of valid fields. Omitted fields are silently absent from the response — no error is raised. When other_contacts is true, only a restricted subset is valid (emailAddresses, names, phoneNumbers, metadata); extended fields like organizations or birthdays may cause validation errors or silent omissions in that mode.
string
Resource name identifying the person for whom to retrieve information (like the authenticated user or a specific contact). Used only when other_contacts is false. Deleted or stale resource_names may return partial records with missing emailAddresses, names, or other fields.
boolean
If true, retrieves ‘Other Contacts’ (people interacted with but not explicitly saved), ignoring resource_name and enabling pagination/sync. If false, retrieves information for the single person specified by resource_name.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_GET_PROFILERetrieves Gmail profile information (email address, aggregate messagesTotal/threadsTotal, historyId) for a user. messagesTotal counts individual emails; threadsTotal counts conversations; neither is per-label — use GMAIL_FETCH_EMAILS with label filters for label-specific counts. The returned historyId seeds incremental sync via GMAIL_LIST_HISTORY; if historyIdTooOld is returned, rescan with GMAIL_FETCH_EMAILS before resuming. Response may be wrapped under a top-level data field; unwrap before reading fields. A successful call confirms mailbox connectivity but not full mailbox access if granted scopes are narrow. Use the returned email address to dynamically identify the authenticated account rather than hard-coding it.

Input Parameters

string
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; passing a raw email address that does not match the connected account may fail or access the wrong mailbox.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_GET_VACATION_SETTINGSTool to retrieve vacation responder settings for a Gmail user. Use when you need to check if out-of-office auto-replies are configured and view their content.

Input Parameters

string
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

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_IMPORT_MESSAGETool 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

string
required
The entire email message in RFC 2822 format, base64url-encoded. This is the raw email message to import into the mailbox.
boolean
Mark the email as permanently deleted (not TRASH) and only visible in Google Vault to a Vault administrator. Only used for Google Workspace accounts.
string
The user’s email address. The special value ‘me’ can be used to indicate the authenticated user.
boolean
Ignore the Gmail spam classifier decision and never mark this email as SPAM in the mailbox.
string ("receivedTime" | "dateHeader")
Source for Gmail’s internal date of the message.
boolean
Process calendar invites in the email and add any extracted meetings to the Google Calendar for this user.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_INSERT_MESSAGETool 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

string
required
The entire email message in RFC 2822 formatted and base64url encoded string. This is the raw message content that will be inserted into the mailbox.
boolean
Mark the email as permanently deleted (not TRASH) and only visible in Google Vault to a Vault administrator. Only used for Google Workspace accounts.
string
The user’s email address. The special value ‘me’ can be used to indicate the authenticated user.
string ("receivedTime" | "dateHeader")
Source for Gmail’s internal date of the message.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_LIST_CSE_IDENTITIESLists a page of client-side encrypted identities and their key-pair associations. A response indicating that CSE is not enabled is returned as an empty list.

Input Parameters

string
The requester’s primary email address. Use ‘me’ to indicate the authenticated user.
integer
The number of identities to return. If not provided, the page size will default to 20 entries.
string
Pagination token indicating which page of identities to return.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_LIST_CSE_KEYPAIRSLists a page of client-side encryption key pairs, including public keys and enablement states. A response indicating that CSE is not enabled is returned as an empty list.

Input Parameters

string
The requester’s primary email address. Use ‘me’ to indicate the authenticated user.
integer
The number of key pairs to return per page. If not provided, the page size will default to 20 entries.
string
Pagination token indicating which page of key pairs to return. Omit to return the first page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_LIST_DRAFTSRetrieves 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. Newly created drafts may not appear immediately. Rapid calls may trigger 403 userRateLimitExceeded or 429 errors; apply exponential backoff (1s, 2s, 4s) before retrying.

Input Parameters

string
User’s mailbox ID; use ‘me’ for the authenticated user.
boolean
If true, fetches full draft details including subject, sender, recipient, body, and timestamp. If false, returns only draft IDs (faster). Increases response payload size; tune max_results accordingly. Use verbose=true before destructive operations to confirm draft identity by subject, recipient, and timestamp.
string
Token from a previous response to retrieve a specific page of drafts. Ordering is non-guaranteed; continue paginating until page_token is absent in the response to retrieve all drafts.
integer
Maximum number of drafts to return per page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_LIST_FILTERSTool 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

string
The user’s email address or the special value ‘me’ to indicate the authenticated user whose filters will be retrieved.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_LIST_FORWARDING_ADDRESSESTool to list all forwarding addresses for the specified Gmail account. Use when you need to retrieve the email addresses that are allowed to be used for forwarding messages.

Input Parameters

string
The user’s email address or the special value ‘me’ to indicate the authenticated user whose forwarding addresses will be retrieved.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_LIST_HISTORYLists Gmail mailbox change history since a known history ID for incremental sync, with optional label and history-type filters and pagination. An empty history list means no records matched the request, not necessarily that no mailbox changes occurred.

Input Parameters

string
The user’s email address. Use ‘me’ to specify the authenticated user.
string
Only return history records involving messages with this label ID.
string
Token to retrieve a specific page of results. If the response includes nextPageToken, loop requests using this parameter until no nextPageToken is returned; failing to paginate will silently miss changes.
integer
Maximum number of history records to return. Default is 100; max is 500.
array
Filter by specific history types. Allowed values: messageAdded, messageDeleted, labelAdded, labelRemoved.
string
required
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. Should be a numeric string. On 404 (historyIdTooOld) or 400 (invalidArgument), recover by fetching a fresh historyId via GMAIL_GET_PROFILE, then perform a one-time full sync via GMAIL_FETCH_EMAILS before resuming incremental calls.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_LIST_LABELSRetrieves 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 and cause silent failures or errors. System labels (INBOX, UNREAD, SPAM, TRASH, etc.) are case-sensitive and must be used exactly as returned; INBOX, SPAM, and TRASH are read-only and cannot be added/removed via label modification tools. The Gmail search ‘label:’ operator accepts display names, but label_ids parameters in tools like GMAIL_FETCH_EMAILS require internal IDs from this tool — mixing conventions yields zero results silently. Do not hardcode label IDs across sessions; refresh via this tool on conflict errors.

Input Parameters

string
Identifies the Gmail account (owner’s email or ‘me’ for authenticated user) for which labels will be listed.
boolean
If true, fetches detailed info for each label including message/thread counts (messagesTotal, messagesUnread, threadsTotal, threadsUnread). This requires additional API calls and may be slower for accounts with many labels. If false (default), returns basic label info (id, name, type) which is faster. Counts are eventually consistent and may lag real-time mailbox state by a few seconds.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_LIST_MESSAGESDEPRECATED: Use GMAIL_FETCH_EMAILS instead. Lists the messages in the user’s mailbox. Use when you need to retrieve a list of email messages with optional filtering by labels or search query.

Input Parameters

string
Only return messages matching the specified query. Supports the same query format as the Gmail search box. For example, ‘from:someuser@example.com is:unread’. Cannot be used when accessing the API using the gmail.metadata scope.
string
The user’s email address or ‘me’ to specify the authenticated user.
array
Only return messages with labels that match all of the specified label IDs. Messages in a thread might have labels that other messages in the same thread don’t have.
string
Page token to retrieve a specific page of results in the list.
integer
Maximum number of messages to return. Defaults to 100. The maximum allowed value is 500.
boolean
Include messages from SPAM and TRASH in the results. Default is false.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_LIST_SEND_ASLists 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

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

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_LIST_SMIME_INFOLists S/MIME certificate configurations for a specified Gmail send-as alias. If Gmail reports that the feature is not enabled, returns an empty list with S/MIME marked disabled.

Input Parameters

string
The user’s email address. The special value ‘me’ can be used to indicate the authenticated user.
string
required
The email address that appears in the ‘From:’ header for mail sent using this alias.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_LIST_THREADSRetrieves a list of email threads from a Gmail account, identified by user_id (email address or ‘me’), 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

string
Filter for threads, using Gmail search query syntax (e.g., ‘from:user@example.com is:unread’). Supported operators include from:, to:, subject:, label:, is:unread, has:attachment, after:, before:. Dates must use YYYY/MM/DD format; date operators are UTC-based. Exact subject phrases require quotes (e.g., subject:'meeting notes').
string
The user’s email address or ‘me’ to specify the authenticated Gmail account.
boolean
If false, returns threads with basic fields (id, snippet, historyId). If true, returns threads with complete message details including headers, body, attachments, and metadata for each message in the thread. Combining verbose=true with large max_results produces very large responses; keep max_results modest when verbose is enabled.
string
Token from a previous response to retrieve a specific page of results; omit for the first page.
integer
Maximum number of threads to return. Hard cap is ~500 per call. For full mailbox coverage, loop using nextPageToken via page_token until absent.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_MODIFY_THREAD_LABELSAdds or removes specified existing label IDs from a Gmail thread, affecting all its messages; ensure the thread ID is valid. To modify a single message only, use a message-level tool instead.

Input Parameters

string
User’s email address or ‘me’ for the authenticated user.
string
required
Immutable ID of the thread to modify.
array
List of label IDs to add to the thread. Must be valid label IDs that exist in the user’s account. System labels use uppercase names (e.g., ‘INBOX’, ‘STARRED’, ‘IMPORTANT’, ‘UNREAD’, ‘SPAM’, ‘TRASH’, ‘SENT’, ‘DRAFT’, ‘CATEGORY_PERSONAL’, ‘CATEGORY_SOCIAL’, ‘CATEGORY_PROMOTIONS’, ‘CATEGORY_UPDATES’, ‘CATEGORY_FORUMS’). Custom labels use the format ‘Label_N’ (e.g., ‘Label_1’, ‘Label_42’). Use GMAIL_LIST_LABELS to discover available label IDs. Accepts either a list or a JSON-encoded string. Note: If a label appears in both add_label_ids and remove_label_ids, the add operation takes priority. Use GMAIL_CREATE_LABEL first if the label does not yet exist, then supply its returned ID here.
array
List of label IDs to remove from the thread. Must be valid label IDs that exist in the user’s account. System labels use uppercase names (e.g., ‘INBOX’, ‘STARRED’, ‘IMPORTANT’, ‘UNREAD’, ‘SPAM’, ‘TRASH’, ‘SENT’, ‘DRAFT’, ‘CATEGORY_PERSONAL’, ‘CATEGORY_SOCIAL’, ‘CATEGORY_PROMOTIONS’, ‘CATEGORY_UPDATES’, ‘CATEGORY_FORUMS’). Custom labels use the format ‘Label_N’ (e.g., ‘Label_1’, ‘Label_42’). Use GMAIL_LIST_LABELS to discover available label IDs. Accepts either a list or a JSON-encoded string. Note: Labels that appear in both add_label_ids and remove_label_ids will be automatically removed from this list (add takes priority).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_MOVE_THREAD_TO_TRASHMoves the specified thread to the trash. Any messages that belong to the thread are also moved to the trash.

Input Parameters

string
The user’s email address. The special value ‘me’ can be used to indicate the authenticated user.
string
required
Required. The ID of the thread to trash. This moves all messages in the thread to trash.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_MOVE_TO_TRASHMoves an existing, non-deleted email message to the trash for the specified user. Trashed messages are recoverable and still count toward storage quota until purged. Prefer this over GMAIL_BATCH_DELETE_MESSAGES when recovery may be needed. For bulk operations, use GMAIL_BATCH_MODIFY_MESSAGES or GMAIL_BATCH_DELETE_MESSAGES instead of repeated calls to this tool.

Input Parameters

string
User’s email address or ‘me’ for the authenticated user.
string
required
Required. The unique identifier of the email message to move to trash. This is a hexadecimal string that can be obtained from listing or fetching emails. Verify the correct message via subject/snippet before trashing to avoid affecting unrelated conversations.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_PATCH_LABELPatches the specified user-created label. System labels (e.g., INBOX, SENT, SPAM) cannot be modified and will be rejected.

Input Parameters

string
required
The ID of the label to update.
string
The display name of the label. At least one of ‘name’, ‘messageListVisibility’, ‘labelListVisibility’, or ‘color’ must be provided. Must be non-empty, unique among user labels, and must not contain ,, /, or ..
object
The color to assign to the label. Color is only available for labels that have their type set to user. At least one of ‘name’, ‘messageListVisibility’, ‘labelListVisibility’, or ‘color’ must be provided. Must include both backgroundColor and textColor subfields; both values must come from Gmail’s predefined color palette — arbitrary hex values or omitting either field causes a 400 error.
string
required
The user’s email address. The special value me can be used to indicate the authenticated user.
string ("labelShow" | "labelShowIfUnread" | "labelHide")
The visibility of the label in the label list in the Gmail web interface. At least one of ‘name’, ‘messageListVisibility’, ‘labelListVisibility’, or ‘color’ must be provided.
string ("show" | "hide")
The visibility of messages with this label in the message list in the Gmail web interface. At least one of ‘name’, ‘messageListVisibility’, ‘labelListVisibility’, or ‘color’ must be provided.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_PATCH_SEND_ASPatches a Gmail send-as alias, including its display name, reply-to address, signature, default status, or SMTP configuration. This tool declares support for service-account OAuth, not standard OAuth.

Input Parameters

string
The user’s email address or the special value ‘me’ to indicate the authenticated user.
object
Configuration for SMTP relay service.
string
An optional HTML signature that is included in messages composed with this alias in the Gmail web UI. This signature is added to new emails only.
boolean
Whether this address is selected as the default ‘From:’ address in situations such as composing a new message or sending a vacation auto-reply. Setting this to true will make other send-as addresses non-default. Only true can be written to this field.
string
A name that appears in the ‘From:’ header for mail sent using this alias. For custom ‘from’ addresses, when empty, Gmail will populate the ‘From:’ header with the name used for the primary address. If the admin has disabled name updates, requests to update this field for the primary login will silently fail.
string
required
The send-as alias email address to update. This is the email address that appears in the ‘From:’ header.
boolean
Whether Gmail should treat this address as an alias for the user’s primary email address. This setting only applies to custom ‘from’ aliases.
string
An optional email address that is included in a ‘Reply-To:’ header for mail sent using this alias. If empty, Gmail will not generate a ‘Reply-To:’ header.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_REMOVE_LABELPermanently deletes an existing user-created Gmail label by ID and removes it from messages and threads where it is applied. This action is deprecated.

Input Parameters

string
User’s email address or ‘me’ for the authenticated user.
string
required
ID of the user-created label to be permanently deleted; must exist and not be a system label.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_REPLY_TO_THREADSends a reply to a Gmail thread using its original subject and quoting the last returned message. Requires a thread ID and at least one recipient, and supports optional file attachments.

Input Parameters

array
Carbon Copy (CC) recipients’ email addresses in format ‘user@domain.com’. Each address must include both username and domain separated by ’@’. At least one of cc, bcc, or recipient_email must be provided.
array
Blind Carbon Copy (BCC) recipients’ email addresses in format ‘user@domain.com’. Each address must include both username and domain separated by ’@’. At least one of cc, bcc, or recipient_email must be provided.
boolean
Indicates if message_body is HTML; if True, body must be valid HTML, if False, body should not contain HTML tags. Mismatch causes recipients to see raw HTML tags as plain text.
string
Identifier for the user sending the reply; ‘me’ refers to the authenticated user.
string
required
Identifier of the Gmail thread for the reply. Must be a valid hexadecimal string, typically 15-16 characters long (e.g., ‘169eefc8138e68ca’). Prefixes like ‘msg-f:’ or ‘thread-f:’ are automatically stripped. Note: Format validation only checks the ID structure; the thread must also exist and be accessible in your Gmail account. Use GMAIL_LIST_THREADS or GMAIL_FETCH_EMAILS to retrieve valid thread IDs. Must be a threadId, not a messageId; passing a messageId can cause the reply to fail or start an unintended new thread.
string
File(s) to attach to the reply. Accepts a single file or a list of files. Total message size including attachments must stay under 25 MB (400 badRequest if exceeded); use Drive links for large files.
string
Content of the reply message, either plain text or HTML.
string
Primary recipient’s email address in format ‘user@domain.com’. Must include both username and domain separated by ’@’. Required if cc and bcc is not provided, else can be optional. Use extra_recipients if you want to send to multiple recipients.
array
Additional ‘To’ recipients’ email addresses in format ‘user@domain.com’ (not Cc or Bcc). Each address must include both username and domain separated by ’@’. Should only be used if recipient_email is also provided.
boolean
Append the sender’s Gmail signature (the ‘Send mail as’ signature configured in Gmail settings) to the message body, ahead of any quoted or forwarded content. Skipped when the body already ends with that signature, when no signature is configured, or when the connection lacks permission to read Gmail settings. Set to false to send the body exactly as provided.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_SEARCH_PEOPLESearches saved contacts and optionally Other Contacts by query, returning matching person records. When both sources are requested, results may be partial if one search fails.

Input Parameters

string
required
Matches contact names, nicknames, email addresses, phone numbers, and organization fields.
integer
Maximum results to return; values >30 are capped to 30 by the API.
string
Comma-separated fields to return (e.g., ‘names,emailAddresses’). When ‘other_contacts’ is true, only ‘emailAddresses’, ‘metadata’, ‘names’, ‘phoneNumbers’ are allowed. For full field access including ‘organizations’, set ‘other_contacts’ to false.
boolean
When True, searches both saved contacts and ‘Other Contacts’ (people you’ve interacted with but not explicitly saved). Note: This restricts person_fields to only ‘emailAddresses’, ‘metadata’, ‘names’, ‘phoneNumbers’. When False, searches only saved contacts but allows all person_fields including ‘organizations’, ‘addresses’, etc.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_SEND_DRAFTSends an existing Gmail draft immediately to the recipients already in its To, Cc, and Bcc headers. The draft’s recipients and content cannot be changed by this action; confirm them before sending.

Input Parameters

string
The user’s email address. The special value me can be used to indicate the authenticated user.
string
required
The ID of the draft to send. Draft IDs are typically alphanumeric strings (e.g., ‘r99885592323229922’). Important: Do not confuse draft_id with message_id - they are different identifiers. Use GMAIL_LIST_DRAFTS to retrieve valid draft IDs, or GMAIL_CREATE_EMAIL_DRAFT to create a new draft and get its ID. IMPORTANT: The draft MUST already have recipients (To, Cc, or Bcc) set - this action cannot add or override recipients. If the draft has no recipients, first create a new draft with recipients using GMAIL_CREATE_EMAIL_DRAFT, or use GMAIL_SEND_EMAIL to send a new email directly.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_SEND_EMAILSends an email immediately through Gmail to specified To, Cc, or Bcc recipients, with a subject or body and optional attachments. Supports plain text or HTML and may append the configured Gmail signature; attachments are limited to 20 MiB in total before encoding.

Input Parameters

array
Carbon Copy (CC) recipients’ email addresses. At least one of ‘to’/‘recipient_email’, ‘cc’, or ‘bcc’ must be provided.
array
Blind Carbon Copy (BCC) recipients’ email addresses. At least one of ‘to’/‘recipient_email’, ‘cc’, or ‘bcc’ must be provided.
string
Email content (plain text or HTML). Either subject or body must be provided for the email to be sent. If HTML, is_html must be True.
boolean
Set to True if the email body contains HTML tags.
string
Subject line of the email. Either subject or body must be provided for the email to be sent.
string
User’s email address; the literal ‘me’ refers to the authenticated user.
string
File(s) to attach. Accepts a single file or a list of files. IMPORTANT: mimetype MUST contain a ’/’ separator - single words like ‘pdf’ or ‘new’ are invalid. Gmail API limits: total message size must not exceed ~25 MB after base64 encoding. Omit or set to null for no attachment. Empty attachment objects (with all fields empty/whitespace) are treated as no attachment.
string
Sender email address for the ‘From’ header. Provide the connected account’s primary email address or a verified alias configured in Gmail’s ‘Send mail as’ settings. When omitted, the action attempts to resolve the primary email address from the authenticated Gmail profile.
string
Primary recipient’s email address. You can also use ‘to’ as an alias for this parameter. At least one of ‘to’/‘recipient_email’, ‘cc’, or ‘bcc’ must be provided. Use extra_recipients if you want to send to multiple recipients. Use the special value ‘me’ to send to your own authenticated email address. Must be a full user@domain address; ‘me’ is not valid here and will fail.
array
Additional ‘To’ recipients’ email addresses (not Cc or Bcc). Should only be used if recipient_email is also provided.
boolean
Append the sender’s Gmail signature (the ‘Send mail as’ signature configured in Gmail settings) to the message body, ahead of any quoted or forwarded content. Skipped when the body already ends with that signature, when no signature is configured, or when the connection lacks permission to read Gmail settings. Set to false to send the body exactly as provided.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_SETTINGS_GET_IMAPRetrieves the IMAP settings for a Gmail user account, including whether IMAP is enabled, auto-expunge behavior, expunge behavior, and maximum folder size.

Input Parameters

string
The user’s email address or the special value ‘me’ to indicate the authenticated user.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_SETTINGS_GET_POPTool to retrieve POP settings for a Gmail account. Use when you need to check the current POP configuration including access window and message disposition.

Input Parameters

string
The user’s email address. The special value ‘me’ can be used to indicate the authenticated user.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_SETTINGS_SEND_AS_GETTool to retrieve a specific send-as alias configuration for a Gmail user. Use when you need to get details about a send-as email address 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

string
The email address of the Gmail user whose send-as alias to retrieve, or the special value ‘me’ to indicate the authenticated user.
string
required
The send-as alias email address to retrieve. This is the email address that appears in the ‘From:’ header.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_STOP_WATCHTool 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

string
The user’s email address. The special value ‘me’ can be used to indicate the authenticated user.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_UNTRASH_MESSAGETool to remove a message from trash in Gmail. Use when you need to restore a previously trashed email message.

Input Parameters

string
User’s email address or ‘me’ for the authenticated user.
string
required
Required. The unique identifier of the email message to remove from trash. This is a hexadecimal string that can be obtained from listing or fetching emails.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_UNTRASH_THREADTool to remove a thread from trash in Gmail. Use when you need to restore a deleted thread and its messages.

Input Parameters

string
The user’s email address. The special value ‘me’ can be used to indicate the authenticated user.
string
required
The ID of the thread to remove from trash.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_UPDATE_CONTACTReplace selected fields on an existing saved Google contact.

Input Parameters

object
required
Google Person resource containing metadata.sources and replacement values. metadata.sources must include a CONTACT source; include that source’s etag for concurrency protection.
array
Source types to include in the returned Person resource.
string
Comma-separated field mask of Person fields to return after the update. Valid values: addresses, ageRanges, biographies, birthdays, calendarUrls, clientData, coverPhotos, emailAddresses, events, externalIds, genders, imClients, interests, locales, locations, memberships, metadata, miscKeywords, names, nicknames, occupations, organizations, phoneNumbers, photos, relations, sipAddresses, skills, urls, userDefined.
string
required
Saved contact resource name in people/{person_id} form.
string
required
Comma-separated field mask of Person fields to replace. Valid values: addresses, biographies, birthdays, calendarUrls, clientData, emailAddresses, events, externalIds, genders, imClients, interests, locales, locations, memberships, miscKeywords, names, nicknames, occupations, organizations, phoneNumbers, relations, sipAddresses, urls, userDefined.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_UPDATE_DRAFTUpdates a Gmail draft by ID by replacing its message. The tool reads the existing draft to preserve omitted recipients, subject and body where applicable, but existing attachments are not preserved unless supplied again.

Input Parameters

array
Carbon Copy (CC) recipients’ email addresses. Each must be a valid email address or display name format.
array
Blind Carbon Copy (BCC) recipients’ email addresses. Each must be a valid email address or display name format.
string
Email body content (plain text or HTML); is_html must be True if HTML. If not provided, previous body is preserved. Can also be provided as ‘message_body’.
boolean
Set to True if body is already formatted HTML. When False, plain text newlines are auto-converted to
tags.
string
Email subject line. If not provided, previous subject is preserved.
string
User’s email address or ‘me’ for the authenticated user.
string
required
The ID of the draft to update. Must be a valid draft ID from GMAIL_LIST_DRAFTS or GMAIL_CREATE_EMAIL_DRAFT.
string
ID of an existing Gmail thread. If provided, the draft will be part of this thread.
string
File(s) to attach to the draft. Accepts a single file or a list of files. Replaces any existing attachments.
string
Primary recipient’s email address. Must be a valid email address (e.g., ‘user@example.com’) or display name format (e.g., ‘John Doe <user@example.com>’). Optional - if not provided, previous recipients are preserved.
array
Additional ‘To’ recipients’ email addresses. Each must be a valid email address or display name format. Should only be used if recipient_email is also provided.
boolean
Append the sender’s Gmail signature (the ‘Send mail as’ signature configured in Gmail settings) to the message body, ahead of any quoted or forwarded content. Skipped when the body already ends with that signature, when no signature is configured, or when the connection lacks permission to read Gmail settings. Set to false to send the body exactly as provided.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_UPDATE_IMAP_SETTINGSTool to update IMAP settings for a Gmail account. Use when you need to modify IMAP configuration such as enabling/disabling IMAP, setting auto-expunge behavior, or configuring folder size limits.

Input Parameters

boolean
Whether IMAP is enabled for the account.
string
The user’s email address. The special value ‘me’ can be used to indicate the authenticated user.
boolean
If this value is true, Gmail will immediately expunge a message when it is marked as deleted in IMAP. Otherwise, Gmail will wait for an update from the client before expunging messages marked as deleted.
integer
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 is interpreted to mean that there is no limit.
string ("expungeBehaviorUnspecified" | "archive" | "trash" | "deleteForever")
The action that will be executed on a message when it is marked as deleted and expunged from the last visible IMAP folder. Possible values: ‘expungeBehaviorUnspecified’ (Unspecified behavior), ‘archive’ (Archive messages marked as deleted), ‘trash’ (Move messages marked as deleted to the trash), ‘deleteForever’ (Immediately and permanently delete messages marked as deleted).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_UPDATE_LABELUpdates an existing Gmail label’s name, visibility settings, or color to help organize the mailbox. Color is available for user labels and requires both a background and text color from Gmail’s supported palette.

Input Parameters

string
required
The ID of the label to update.
string
The display name of the label.
object
Color settings for the label. Both backgroundColor and textColor must be provided together.
string
The user’s email address. The special value me can be used to indicate the authenticated user.
string ("labelShow" | "labelShowIfUnread" | "labelHide")
Visibility of the label in the label list (Gmail sidebar).
string ("show" | "hide")
Visibility of messages with this label in the message list.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_UPDATE_LANGUAGE_SETTINGSTool to update the language settings for a Gmail user. Use when you need to change the display language preference for the authenticated user or a specific Gmail account. The returned displayLanguage may differ from the requested value if Gmail selects a close variant.

Input Parameters

string
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.
string
required
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, ‘de’ for German, ‘en’ for English). The set of languages supported by Gmail evolves over time. Note: Gmail may save a close variant if the requested language is not directly supported. For example, if you request a regional variant that’s not available, Gmail may save the base language instead.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_UPDATE_POP_SETTINGSTool to update POP settings for a Gmail account. Use when you need to configure POP access window or message disposition behavior.

Input Parameters

string
The user’s email address. The special value ‘me’ can be used to indicate the authenticated user.
string ("dispositionUnspecified" | "leaveInInbox" | "archive" | "trash" | "markRead")
The action that will be executed on a message after it has been fetched via POP.
string ("accessWindowUnspecified" | "disabled" | "fromNowOn" | "allMail")
The range of messages which are accessible via POP.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_UPDATE_SEND_ASUpdates a Gmail send-as alias, including its display name, signature, reply-to address, or SMTP settings; Gmail sanitizes HTML signatures before saving. The tool declares support for service-account OAuth, not standard OAuth; non-primary addresses require domain-wide delegation.

Input Parameters

string
The email address of the Gmail user whose send-as alias to update, or the special value ‘me’ to indicate the authenticated user.
object
SMTP relay configuration for the send-as alias.
string
Optional HTML signature for messages composed with this alias in Gmail web UI. Gmail sanitizes HTML before saving. Only added to new emails.
boolean
Set to true to make this the default ‘From:’ address for composing messages and vacation auto-replies. Setting true makes the previous default false. Only legal writable value is true.
string
Name to appear in ‘From:’ header. For custom from addresses, Gmail populates with primary account name if empty. Admin restrictions may silently fail updates to primary login name.
string
required
The send-as alias email address to update. This is the email address that appears in the ‘From:’ header.
boolean
Whether Gmail treats this address as an alias for the user’s primary email. Only applies to custom from aliases.
string
Optional email address for ‘Reply-To:’ header. Gmail omits header if empty.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_UPDATE_VACATION_SETTINGSTool to update vacation responder settings for a Gmail user. Use when you need to configure out-of-office auto-replies.

Input Parameters

string
The user’s email address. The special value ‘me’ can be used to indicate the authenticated user.
string
An optional end time for sending auto-replies (epoch ms). When this is specified, Gmail will automatically reply only to messages that it receives before the end time. If both startTime and endTime are specified, startTime must precede endTime.
string
An optional start time for sending auto-replies (epoch ms). When this is specified, Gmail will automatically reply only to messages that it receives after the start time. If both startTime and endTime are specified, startTime must precede endTime.
boolean
Flag that controls whether Gmail automatically replies to messages.
string
Optional text to prepend to the subject line in vacation responses. In order to enable auto-replies, either the response subject or the response body must be nonempty.
string
Response body in HTML format. Gmail will sanitize the HTML before storing it. If both response_body_plain_text and response_body_html are specified, response_body_html will be used.
boolean
Flag that determines whether responses are sent to recipients who are outside of the user’s domain. This feature is only available for Google Workspace users.
boolean
Flag that determines whether responses are sent to recipients who are not in the user’s list of contacts.
string
Response body in plain text format. If both response_body_plain_text and response_body_html are specified, response_body_html will be used.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: GMAIL_WHO_AM_IReturn the identity (email, name) of the connected Gmail account.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not

Triggers

Slug: GMAIL_EMAIL_SENT_TRIGGERType: pollTriggers when a Gmail message is sent by the authenticated user. It polls the ‘SENT’ label and emits metadata including sender, recipients, subject, timestamp, and thread ID.

Configuration

number
Deprecated: use polling_interval on the trigger instance instead. Minutes between checks for new events.
string
Optional additional Gmail search query to further filter sent messages. Uses Gmail search syntax (e.g., to:example@domain.com subject:report).
string
The user’s email address or ‘me’ for the authenticated user.

Payload

array
The list of attachments in the sent message
string
Bcc recipients
string
Cc recipients
string
Gmail message ID
string
The text of the sent message
string
Timestamp of the sent message in ISO format
object
Raw Gmail payload
string
Comma-separated list of all recipients (To, Cc, Bcc)
string
Sender email
string
Email subject
string
Gmail thread ID
string
To recipients
Slug: GMAIL_NEW_GMAIL_MESSAGEType: pollTriggers when a new message is received in Gmail.

Configuration

number
Deprecated: use polling_interval on the trigger instance instead. Minutes between checks for new events.
string
Filter messages by a single label ID. Labels identify the status or category of messages. Supported labels include ‘INBOX’, ‘SPAM’, ‘TRASH’, ‘UNREAD’, ‘STARRED’, ‘IMPORTANT’, ‘CATEGORY_PERSONAL’, ‘CATEGORY_SOCIAL’, ‘CATEGORY_PROMOTIONS’, ‘CATEGORY_UPDATES’, and ‘CATEGORY_FORUMS’. For complex label filtering, use the ‘query’ parameter instead.
string
Advanced Gmail search using the same syntax as Gmail’s search box. Use ‘AND’ for messages that match all conditions, ‘OR’ for any condition. Search by sender (from:email@domain.com), labels (label:inbox), status (is:unread), attachments (has:attachment), dates (after:2023/1/1), and more. If specified, this takes precedence over labelIds.
string
The user’s email address or ‘me’ for the authenticated user.

Payload

array
The list of attachments in the message
string
The raw Gmail message ID
array
The Gmail label IDs applied to the message
string
The message ID of the message
string
The text of the message
string
The timestamp of the message
object
The payload of the message
object
The preview payload of the message
string
The sender of the message
string
The subject of the message
string
The thread ID of the message
string
The recipient of the message