# Gmail Your Toolhouse AI Worker can connect to Gmail using 63 specialized tools. ## Auth Connection This service requires an auth connection to use its tools. You can set this up in your Toolhouse dashboard under [Auth Connections](https://toolhouse.app/auth-connections?authkit_slugs=gmail). ## Tools (63) ### Gmail Add Label To Email Integration name: **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). #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------ | :------: | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | string | | `"me"` | User's email address or 'me' for the authenticated user. | | `message_id` | string | ✅ | `"1a2b3c4d5e6f7890"` | Immutable ID of the message to modify. Gmail message IDs are 15-16 character 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. | | `add_label_ids` | array | | `"STARRED"` | 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\_'). 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. | | `remove_label_ids` | array | | `"UNREAD"` | 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\_'). 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. | *** ### Gmail Batch Delete Messages Integration name: **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 (e.g., retention enforcement, mailbox hygiene). 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 rateLimitExceeded or 403 userRateLimitExceeded errors; apply exponential backoff. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------ | ------ | :------: | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `userId` | string | | `"me"` | User's email address or 'me' for the authenticated user. | | `messageIds` | array | ✅ | `["18c5f5d1a2b3c4d5","18c5f5d1a2b3c4d6"]` | List of Gmail message IDs to delete. Each ID must be a 15-16 character hexadecimal string (e.g., '18c5f5d1a2b3c4d5'). Obtain IDs from actions like GMAIL\_FETCH\_EMAILS or GMAIL\_LIST\_THREADS - do not use human-readable descriptions. | *** ### Gmail Batch Modify Messages Integration name: **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 rateLimitExceeded or 403 userRateLimitExceeded; apply exponential backoff. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ---------------- | ------ | :------: | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `userId` | string | | `"me"` | User's email address or 'me' for the authenticated user. | | `messageIds` | array | ✅ | `["18c5f5d1a2b3c4d5","18c5f5d1a2b3c4d6"]` | 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. | | `addLabelIds` | array | | `["INBOX","STARRED"]` | 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. | | `removeLabelIds` | array | | `["UNREAD"]` | 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. | *** ### Gmail Create Email Draft Integration name: **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 (ensure `is_html=True` for HTML), attachments, and threading. Returns a draft\_id that must be used as-is with GMAIL\_SEND\_DRAFT — synthetic or stale IDs will fail. When creating a draft reply to an existing thread (thread\_id provided), leave subject empty to stay in the same thread; setting a subject will create a NEW thread instead. HTTP 429 may occur on rapid creation/send sequences; apply exponential backoff. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cc` | array | | `["cc.recipient1@example.com","CC User "]` | Carbon Copy (CC) recipients' email addresses. Each must be a valid email address (e.g., '') or display name format (e.g., 'John Doe '). Plain names without email addresses are NOT valid. Optional for drafts (recipients can be added later before sending). | | `bcc` | array | | `["bcc.recipient@example.com","BCC User "]` | Blind Carbon Copy (BCC) recipients' email addresses. Each must be a valid email address (e.g., '') or display name format (e.g., 'Bob Jones '). Plain names without email addresses are NOT valid. Optional for drafts (recipients can be added later before sending). | | `body` | string | | `"Hello Team,\n\nPlease find the attached report for your review.\n\nBest regards,\nYour Name"` | 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'. | | `is_html` | boolean | | `true` |

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.

| | `subject` | string | | `"Project Update Q3"` | 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. | | `user_id` | string | | `"me"` | User's email address or 'me' for the authenticated user. | | `thread_id` | string | | `"17f45ec49a9c3f1b"` | 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. | | `attachment` | — | | `{"name":"report.pdf","s3key":"uploads/abc123.pdf","mimetype":"application/pdf"}` | File(s) to attach to the email. Accepts a single file or a list of files. Must be a dict (or list of dicts) with fields: name (filename), mimetype (e.g., 'application/pdf'), and s3key (obtained from a prior upload/download response — local paths or guessed keys will fail). Total message size including base64-encoded attachments must be under 25 MB; use shareable links (e.g., Google Drive) for larger files. | | `recipient_email` | string | | `"john.doe@example.com"` | Primary recipient's email address. Must be a valid email address (e.g., '') or display name format (e.g., 'John Doe '). 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. | | `extra_recipients` | array | | `["jane.doe@example.com","Jane Doe "]` | Additional 'To' recipients' email addresses (not Cc or Bcc). Each must be a valid email address (e.g., ''), display name format (e.g., 'Jane Doe '), or 'me' for the authenticated user. Plain names without email addresses are NOT valid. Should only be used if recipient\_email is also provided. | *** ### Gmail Create Filter Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ---------- | ------ | :------: | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `action` | object | ✅ | — | REQUIRED. Action that the filter will perform on messages matching the criteria. At least one action field must be specified. | | `user_id` | string | | `"me"` | The user's email address or the special value 'me' to indicate the authenticated user for whom the filter will be created. | | `criteria` | object | ✅ | — | REQUIRED. Message matching criteria that determines which messages the filter will apply to. At least one criteria field must be specified. | *** ### Gmail Create Label Integration name: **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, GMAIL\_BATCH\_MODIFY\_MESSAGES, and GMAIL\_MODIFY\_THREAD\_LABELS — those tools do not accept display names. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------------- | ------ | :------: | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `user_id` | string | | `"me"` | The email address of the user in whose account the label will be created. | | `label_name` | string | ✅ | `"Work"` | 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. | | `text_color` | string | | `"BLACK"` | 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: 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. | | `background_color` | string | | `"YELLOW"` | 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: 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. | | `label_list_visibility` | string | | `"labelShow"` | 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). | | `message_list_visibility` | string | | `"show"` | 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. | *** ### Gmail Create Prompt Post Integration name: **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. Use when you need to send a single prompt and receive a response without maintaining conversation context. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ---------------- | ------ | :------: | ------------------------------------ | -------------------------------------------------------------------------- | | `config` | object | | — | Agent configuration. Controls behavior, capabilities, and document access. | | `format` | string | | — | Controls how directives in the response are formatted. | | `message` | string | ✅ | `"Summarize my latest blog posts"` | The prompt message to send to the agent | | `instructions` | string | | `"Be concise and use bullet points"` | Custom instructions for the agent | | `organizationId` | string | ✅ | `"abc123"` | Your Sanity organization ID | *** ### Gmail Delete Draft Integration name: **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. Ensure the draft exists and the user has necessary permissions for the given `user_id`. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ---------- | ------ | :------: | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | string | | `"me"` | User's email address or 'me' for the authenticated user; 'me' is recommended. | | `draft_id` | string | ✅ | `"r-8388446164079304564"` | 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. | *** ### Gmail Delete Filter Integration name: **GMAIL\_DELETE\_FILTER** Tool to permanently delete a Gmail filter by its ID. Use when you need to remove an existing email filtering rule. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ----------- | ------ | :------: | ------------------------------------------ | ------------------------------------------------------------------------------------------------ | | `user_id` | string | | `"me"` | User's email address or 'me' for the authenticated user. | | `filter_id` | string | ✅ | `"ANe1Bmhf1zE0KtM6340kAXudxukJADqVJ6jVVA"` | The ID of the filter to be deleted. Filter IDs can be obtained from GMAIL\_LIST\_FILTERS action. | *** ### Gmail Delete Label Integration name: **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 action instead. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ---------- | ------ | :------: | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | string | | `"me"` | User's email address or 'me' for the authenticated user. | | `label_id` | string | ✅ | `"Label_1"` | ID of the user-created label to be permanently DELETED from the account. Must be a custom label ID (format: 'Label\_' 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. | *** ### Gmail Delete Message Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------ | ------ | :------: | -------------------- | ------------------------------------------------------------------------------ | | `user_id` | string | | `"me"` | User's email address. The special value 'me' refers to the authenticated user. | | `message_id` | string | ✅ | `"185120e4428ba8cf"` | Identifier of the email message to delete. | *** ### Gmail Delete Thread Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------- | ------ | :------: | -------------------- | ------------------------------------------------------------------------------ | | `id` | string | ✅ | `"19c8e0ea407b9cf9"` | ID of the Thread to delete. | | `user_id` | string | | `"me"` | User's email address. The special value 'me' refers to the authenticated user. | *** ### Gmail Fetch Emails Integration name: **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); always null-check before accessing messageId or threadId. Null-check subject and header fields before string operations. For large result sets, prefer ids\_only=true or metadata-only listing, then hydrate via GMAIL\_FETCH\_MESSAGE\_BY\_MESSAGE\_ID. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | -------------------- | ------- | :------: | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | | `"from:john@example.com is:unread"` | 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. | | `user_id` | string | | `"me"` | 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. | | `verbose` | boolean | | `true` | 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. | | `ids_only` | boolean | | `true` | 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. | | `label_ids` | array | | `"INBOX"` | 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. | | `page_token` | 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. | | `max_results` | integer | | `"10"` | 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. | | `include_payload` | boolean | | `true` | 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. | | `include_spam_trash` | boolean | | `true` | Set to true to include messages from 'SPAM' and 'TRASH'. | *** ### Gmail Fetch Message By Message Id Integration name: **GMAIL\_FETCH\_MESSAGE\_BY\_MESSAGE\_ID** Fetches a specific email message by its ID, provided the `message_id` exists and is accessible to the authenticated `user_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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------ | ------ | :------: | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `format` | string | | `"metadata"` | 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. | | `user_id` | string | | `"user@example.com"` | User's email address or 'me' for the authenticated user. | | `message_id` | string | ✅ | `"19b11732c1b578fd"` | 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. | *** ### Gmail Fetch Message By Thread Id Integration name: **GMAIL\_FETCH\_MESSAGE\_BY\_THREAD\_ID** Retrieves messages from a Gmail thread using its `thread_id`, where the thread must be accessible by the specified `user_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. Check `labelIds` per message to filter drafts. Concurrent bulk calls may trigger 403 `userRateLimitExceeded` or 429; cap concurrency \~10 and use exponential backoff. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------ | ------ | :------: | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | string | | `"me"` | The email address of the user. | | `thread_id` | string | ✅ | `"19bf77729bcb3a44"` | 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. | | `page_token` | string | | `"CiAKGhIKJdealEffectivelyPageToken"` | 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. | *** ### Gmail Forward Message Integration name: **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. Messages near Gmail's size limits may fail; reconstruct a smaller draft if needed. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ----------------- | ------ | :------: | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cc` | array | | `["cc1@example.com","cc2@example.com"]` | List of email addresses to CC. | | `bcc` | array | | `["bcc1@example.com","bcc2@example.com"]` | List of email addresses to BCC. | | `user_id` | string | | `"me"` | User's email address or 'me' for the authenticated user. | | `message_id` | string | ✅ | `"17f45ec49a9c3f1b"` | 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'. | | `recipients` | array | ✅ | `["john.doe@example.com","jane.smith@example.com"]` | List of email addresses to forward the message to. | | `additional_text` | string | | `"Please see the forwarded message below."` | Optional additional text to include before the forwarded content. | *** ### Gmail Get Attachment Integration name: **GMAIL\_GET\_ATTACHMENT** Retrieves a specific attachment by ID from a message in a user's Gmail mailbox, requiring valid message and attachment IDs. Returns base64url-encoded binary data (up to \~25 MB); the downloaded file location is at data.file.s3url (also exposes mimetype and name; no s3key). Attachments exceeding \~25 MB may be exposed as Google Drive links — use GOOGLEDRIVE\_DOWNLOAD\_FILE when a Drive file\_id is present instead. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------------- | ------ | :------: | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | string | | `"me"` | User's email address ('me' for authenticated user). | | `file_name` | string | ✅ | `"invoice.pdf"` | Desired filename for the downloaded attachment. This is a required string field - do not pass null. | | `message_id` | string | ✅ | `"18exampleMessageId7f9"` | 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). | | `attachment_id` | string | ✅ | `"ANGjdJ8sZ7example1234"` | 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. | *** ### Gmail Get Auto Forwarding Integration name: **GMAIL\_GET\_AUTO\_FORWARDING** Tool 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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------- | ------ | :------: | ------- | ------------------------------------------------------------------------------------------------ | | `user_id` | string | | `"me"` | The user's email address. The special value 'me' can be used to indicate the authenticated user. | *** ### Gmail Get Contacts Integration name: **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'; email-header-only senders are out of scope. Contact records may have sparse data — handle missing fields gracefully. People API shares a per-user QPS quota; HTTP 429 requires exponential backoff (1s, 2s, 4s). #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------------ | ------- | :------: | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `page_token` | 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. | | `person_fields` | string | | `"addresses"` | Comma-separated person fields to retrieve for each contact (e.g., 'names,emailAddresses'). | | `resource_name` | string | | — | Identifier for the person resource whose connections are listed; use 'people/me' for the authenticated user. | | `include_other_contacts` | 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. | *** ### Gmail Get Draft Integration name: **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. The format parameter controls the level of detail returned. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ---------- | ------ | :------: | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `format` | string | | `"full"` | 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 | | `"me"` | The user's email address. The special value `me` can be used to indicate the authenticated user. | | `draft_id` | string | ✅ | `"r99885592323229922"` | 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. | *** ### Gmail Get Filter Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------- | ------ | :------: | ------------------------------------------ | -------------------------------------------------------------------------------------- | | `id` | string | ✅ | `"ANe1BmjnwmKdVlXGMLeKsv98UJGFe82pUGCsVQ"` | The ID of the filter to be fetched. | | `user_id` | string | | `"me"` | The user's email address or the special value 'me' to indicate the authenticated user. | *** ### Gmail Get Label Integration name: **GMAIL\_GET\_LABEL** Gets details for a specified Gmail label. Use this to retrieve label information including name, type, visibility settings, message/thread counts, and color. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------- | ------ | :------: | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | `"INBOX"` | 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 | | `"me"` | The user's email address. The special value 'me' can be used to indicate the authenticated user. | *** ### Gmail Get Language Settings Integration name: **GMAIL\_GET\_LANGUAGE\_SETTINGS** Tool 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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------- | ------ | :------: | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | string | | `"me"` | 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. | *** ### Gmail Get People Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ---------------- | ------- | :------: | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sources` | 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. | | `page_size` | integer | | — | The number of 'Other Contacts' to return per page. Applicable only when `other_contacts` is true. | | `page_token` | 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. | | `sync_token` | 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. | | `person_fields` | string | | `"names,emailAddresses"` | 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. | | `resource_name` | string | | `"people/me"` | 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. | | `other_contacts` | 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`. | *** ### Gmail Get Profile Integration name: **GMAIL\_GET\_PROFILE** Retrieves 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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------- | ------ | :------: | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `user_id` | string | | `"user@example.com"` | 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. | *** ### Gmail Get Vacation Settings Integration name: **GMAIL\_GET\_VACATION\_SETTINGS** Tool 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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------- | ------ | :------: | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | string | | `"me"` | 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. | *** ### Gmail Import Message Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ---------------------- | ------- | :------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `raw` | string | ✅ | `"RnJvbTogdGVzdEBleGFtcGxlLmNvbQ0KVG86IHJlY2lwaWVudEBleGFtcGxlLmNvbQ0KU3ViamVjdDogVGVzdCBJbXBvcnQgTWVzc2FnZQ0KDQpUaGlzIGlzIGEgdGVzdCBlbWFpbCBtZXNzYWdlIGZvciBpbXBvcnRpbmcgdmlhIEdtYWlsIEFQSS4="` | The entire email message in RFC 2822 format, base64url-encoded. This is the raw email message to import into the mailbox. | | `deleted` | 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. | | `user_id` | string | | `"me"` | The user's email address. The special value 'me' can be used to indicate the authenticated user. | | `never_mark_spam` | boolean | | — | Ignore the Gmail spam classifier decision and never mark this email as SPAM in the mailbox. | | `internal_date_source` | string | | `"receivedTime"` | Source for Gmail's internal date of the message. | | `process_for_calendar` | boolean | | — | Process calendar invites in the email and add any extracted meetings to the Google Calendar for this user. | *** ### Gmail Insert Message Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | -------------------- | ------- | :------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `raw` | string | ✅ | `"RnJvbTogdGVzdEBleGFtcGxlLmNvbQ0KVG86IHRlc3RAZXhhbXBsZS5jb20NCkNvbnRlbnQtVHlwZTogdGV4dC9wbGFpbjsgY2hhcnNldD0idXRmLTgiDQpNSU1FLVZlcnNpb246IDEuMA0KU3ViamVjdDogVGVzdCBNZXNzYWdlDQoNCkhpLCB0aGlzIGlzIGEgdGVzdCBtZXNzYWdlLg=="` | 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. | | `deleted` | 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. | | `user_id` | string | | `"me"` | The user's email address. The special value `me` can be used to indicate the authenticated user. | | `internalDateSource` | string | | — | Source for Gmail's internal date of the message. | *** ### Gmail List Cse Identities Integration name: **GMAIL\_LIST\_CSE\_IDENTITIES** Tool to list client-side encrypted identities for an authenticated user. Use when you need to retrieve CSE identity configurations including key pair associations. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------ | ------- | :------: | ---------------- | ---------------------------------------------------------------------------------------------- | | `user_id` | string | | `"me"` | The requester's primary email address. Use 'me' to indicate the authenticated user. | | `page_size` | integer | | `20` | The number of identities to return. If not provided, the page size will default to 20 entries. | | `page_token` | string | | `"ABCDEF123456"` | Pagination token indicating which page of identities to return. | *** ### Gmail List Cse Keypairs Integration name: **GMAIL\_LIST\_CSE\_KEYPAIRS** Tool to list client-side encryption key pairs for an authenticated user. Use when you need to retrieve CSE keypair configurations including public keys and enablement states. Supports pagination for large result sets. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------ | ------- | :------: | ---------------- | ------------------------------------------------------------------------------------------------------ | | `user_id` | string | | `"me"` | The requester's primary email address. Use 'me' to indicate the authenticated user. | | `page_size` | integer | | `20` | The number of key pairs to return per page. If not provided, the page size will default to 20 entries. | | `page_token` | string | | `"ABCDEF123456"` | Pagination token indicating which page of key pairs to return. Omit to return the first page. | *** ### Gmail List Drafts Integration name: **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. Newly created drafts may not appear immediately. Rapid calls may trigger 403 userRateLimitExceeded or 429 errors; apply exponential backoff (1s, 2s, 4s) before retrying. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------- | ------- | :------: | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `user_id` | string | | `"me"` | User's mailbox ID; use 'me' for the authenticated user. | | `verbose` | boolean | | `true` | 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. | | `page_token` | string | | `"CiaKJDhWSE5UURE9PSIsImMiOiJhYmMxMjMifQ=="` | 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. | | `max_results` | integer | | `10` | Maximum number of drafts to return per page. | *** ### Gmail List Filters Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------- | ------ | :------: | ------- | ---------------------------------------------------------------------------------------------------------------------- | | `user_id` | string | | `"me"` | The user's email address or the special value 'me' to indicate the authenticated user whose filters will be retrieved. | *** ### Gmail List Forwarding Addresses Integration name: **GMAIL\_LIST\_FORWARDING\_ADDRESSES** Tool 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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------- | ------ | :------: | ------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | string | | `"me"` | The user's email address or the special value 'me' to indicate the authenticated user whose forwarding addresses will be retrieved. | *** ### Gmail List History Integration name: **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; without it, incremental sync is unreliable. An empty history list in the response is valid and means no new changes occurred. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `user_id` | string | | `"me"` | The user's email address. Use 'me' to specify the authenticated user. | | `label_id` | string | | `"INBOX"` | Only return history records involving messages with this label ID. | | `page_token` | string | | `"ABCDEF123456"` | 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. | | `max_results` | integer | | `100` | Maximum number of history records to return. Default is 100; max is 500. | | `history_types` | array | | `["messageAdded","labelRemoved"]` | Filter by specific history types. Allowed values: messageAdded, messageDeleted, labelAdded, labelRemoved. | | `start_history_id` | string | ✅ | `"1234567890"` | 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. | *** ### Gmail List Labels Integration name: **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 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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ----------------- | ------- | :------: | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | string | | `"me"` | Identifies the Gmail account (owner's email or 'me' for authenticated user) for which labels will be listed. | | `include_details` | boolean | | `true` | 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. | *** ### Gmail List Messages Integration name: **GMAIL\_LIST\_MESSAGES** DEPRECATED: 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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | -------------------- | ------- | :------: | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `q` | string | | `"is:unread"` | Only return messages matching the specified query. Supports the same query format as the Gmail search box. For example, 'from: is:unread'. Cannot be used when accessing the API using the gmail.metadata scope. | | `user_id` | string | | `"me"` | The user's email address or 'me' to specify the authenticated user. | | `label_ids` | array | | `["INBOX"]` | 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. | | `page_token` | string | | `"NextPageToken123"` | Page token to retrieve a specific page of results in the list. | | `max_results` | integer | | `10` | Maximum number of messages to return. Defaults to 100. The maximum allowed value is 500. | | `include_spam_trash` | boolean | | `true` | Include messages from SPAM and TRASH in the results. Default is false. | *** ### Gmail List Send As Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------- | ------ | :------: | ------- | ------------------------------------------------------------------------------------------------------------------------------ | | `user_id` | string | | `"me"` | The user's email address or the special value 'me' to indicate the authenticated user whose send-as aliases will be retrieved. | *** ### Gmail List Smime Info Integration name: **GMAIL\_LIST\_SMIME\_INFO** Lists S/MIME configs for the specified send-as alias. Use when you need to retrieve all S/MIME certificate configurations associated with a specific send-as email address. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------------- | ------ | :------: | --------------------- | ------------------------------------------------------------------------------------------------ | | `user_id` | string | | `"me"` | The user's email address. The special value 'me' can be used to indicate the authenticated user. | | `send_as_email` | string | ✅ | `"alias@example.com"` | The email address that appears in the 'From:' header for mail sent using this alias. | *** ### Gmail List Threads Integration name: **GMAIL\_LIST\_THREADS** Retrieves 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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------- | ------- | :------: | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | | `"is:unread"` | Filter for threads, using Gmail search query syntax (e.g., 'from: 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'`). | | `user_id` | string | | `"me"` | The user's email address or 'me' to specify the authenticated Gmail account. | | `verbose` | boolean | | `true` | 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. | | `page_token` | string | | `"abcPageToken123"` | Token from a previous response to retrieve a specific page of results; omit for the first page. | | `max_results` | integer | | `"10"` | Maximum number of threads to return. Hard cap is \~500 per call. For full mailbox coverage, loop using `nextPageToken` via `page_token` until absent. | *** ### Gmail Modify Thread Labels Integration name: **GMAIL\_MODIFY\_THREAD\_LABELS** Adds 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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------ | :------: | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | string | | `"user@example.com"` | User's email address or 'me' for the authenticated user. | | `thread_id` | string | ✅ | `"18ea7715b619f09c"` | Immutable ID of the thread to modify. | | `add_label_ids` | array | | `"STARRED"` | 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. | | `remove_label_ids` | array | | `"IMPORTANT"` | 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). | *** ### Gmail Move Thread To Trash Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ----------- | ------ | :------: | -------------------- | ------------------------------------------------------------------------------------------------ | | `user_id` | string | | `"me"` | The user's email address. The special value 'me' can be used to indicate the authenticated user. | | `thread_id` | string | ✅ | `"19c8e0f136c69508"` | Required. The ID of the thread to trash. This moves all messages in the thread to trash. | *** ### Gmail Move To Trash Integration name: **GMAIL\_MOVE\_TO\_TRASH** Moves 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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------ | ------ | :------: | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | string | | `"user@example.com"` | User's email address or 'me' for the authenticated user. | | `message_id` | string | ✅ | `"1875f42779f726f2"` | 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. | *** ### Gmail Patch Label Integration name: **GMAIL\_PATCH\_LABEL** Patches the specified user-created label. System labels (e.g., INBOX, SENT, SPAM) cannot be modified and will be rejected. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ----------------------- | ------ | :------: | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | ✅ | `"LABEL_123"` | The ID of the label to update. | | `name` | string | | `"My Updated Label"` | 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 `.`. | | `color` | 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. | | `userId` | string | ✅ | `"me"` | The user's email address. The special value `me` can be used to indicate the authenticated user. | | `labelListVisibility` | string | | `"labelShow"` | 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. | | `messageListVisibility` | string | | `"show"` | 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. | *** ### Gmail Patch Send As Integration name: **GMAIL\_PATCH\_SEND\_AS** Tool to patch the specified send-as alias for a Gmail user. Use when you need to update properties of an existing send-as email address such as display name, reply-to address, signature, default status, or SMTP configuration. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | string | | `"me"` | The user's email address or the special value 'me' to indicate the authenticated user. | | `smtp_msa` | object | | — | Configuration for SMTP relay service. | | `signature` | string | | `"

Best regards,
John Doe

"` | 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. | | `is_default` | boolean | | `true` | 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. | | `display_name` | string | | `"Composio Partnerships"` | 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. | | `send_as_email` | string | ✅ | `"alias@example.com"` | The send-as alias email address to update. This is the email address that appears in the 'From:' header. | | `treat_as_alias` | boolean | | `true` | Whether Gmail should treat this address as an alias for the user's primary email address. This setting only applies to custom 'from' aliases. | | `reply_to_address` | string | | `"noreply@example.com"` | 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. | *** ### Gmail Remove Label Integration name: **GMAIL\_REMOVE\_LABEL** DEPRECATED: Use GMAIL\_DELETE\_LABEL instead. Permanently deletes a specific, existing user-created Gmail label by its ID for a user; cannot delete system labels. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ---------- | ------ | :------: | ------------- | --------------------------------------------------------------------------------------------- | | `user_id` | string | | `"me"` | User's email address or 'me' for the authenticated user. | | `label_id` | string | ✅ | `"Label_123"` | ID of the user-created label to be permanently deleted; must exist and not be a system label. | *** ### Gmail Reply To Thread Integration name: **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`. Supports attachments via the `attachment` parameter with `name`, `mimetype`, and `s3key` fields. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `cc` | array | | `["cc.recipient1@example.com","cc.recipient2@example.com"]` | Carbon Copy (CC) recipients' email addresses in format ''. Each address must include both username and domain separated by '@'. At least one of cc, bcc, or recipient\_email must be provided. | | `bcc` | array | | `["bcc.recipient@example.com"]` | Blind Carbon Copy (BCC) recipients' email addresses in format ''. Each address must include both username and domain separated by '@'. At least one of cc, bcc, or recipient\_email must be provided. | | `is_html` | boolean | | `true` | 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. | | `user_id` | string | | `"me"` | Identifier for the user sending the reply; 'me' refers to the authenticated user. | | `thread_id` | string | ✅ | `"169eefc8138e68ca"` | 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. | | `attachment` | — | | `{"name":"report.pdf","s3key":"uploads/abc123.pdf","mimetype":"application/pdf"}` | File(s) to attach to the reply. Accepts a single file or a list of files. Requires `name`, `mimetype`, and `s3key` fields; `s3key` must come from a prior upload/download response. Total message size including attachments must stay under 25 MB (400 badRequest if exceeded); use Drive links for large files. | | `message_body` | string | | `"Dear Sir, Nice talking to you. Yours respectfully, John"` | Content of the reply message, either plain text or HTML. | | `recipient_email` | string | | `"john@doe.com"` | Primary recipient's email address in format ''. 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. | | `extra_recipients` | array | | `["jane.doe@example.com","another.person@example.com"]` | Additional 'To' recipients' email addresses in format '' (not Cc or Bcc). Each address must include both username and domain separated by '@'. Should only be used if recipient\_email is also provided. | *** ### Gmail Search People Integration name: **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 — people existing solely in message headers won't appear; use GMAIL\_FETCH\_EMAILS for those. Results may be zero or multiple; never auto-select from ambiguous results. Results paginate via next\_page\_token; follow until empty and deduplicate by email. Many records lack emailAddresses or names even when requested — handle missing keys. Directory/organization policies may suppress entries. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ---------------- | ------- | :------: | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | ✅ | — | Matches contact names, nicknames, email addresses, phone numbers, and organization fields. | | `page_size` | integer | | — | Maximum results to return; values >30 are capped to 30 by the API. | | `person_fields` | string | | `"addresses"` | 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. | | `other_contacts` | 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. | *** ### Gmail Send Draft Integration name: **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). The Gmail API's drafts/send endpoint sends drafts to whatever recipients are already set in the draft's To, Cc, and Bcc headers - it cannot add or override recipients. If the draft has no recipients, you must either: 1. Create a new draft with recipients using GMAIL\_CREATE\_EMAIL\_DRAFT, then send it 2. Use GMAIL\_SEND\_EMAIL to send a new email directly with recipients. Send is immediate and irreversible — confirm recipients and content before calling. No scheduling support; trigger at the desired UTC time externally. Gmail enforces \~25 MB message size limit and daily send caps (\~500 recipients/day personal, \~2,000/day Workspace). #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ---------- | ------ | :------: | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | string | | `"me"` | The user's email address. The special value `me` can be used to indicate the authenticated user. | | `draft_id` | string | ✅ | `"r99885592323229922"` | 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. | *** ### Gmail Send Email Integration name: **GMAIL\_SEND\_EMAIL** Sends an email via Gmail API using the authenticated user's Google profile display name. Sends immediately and is irreversible — confirm recipients, subject, body, and attachments before calling. At least one of 'to' (or 'recipient\_email'), 'cc', or 'bcc' must be provided. At least one of subject or body must be provided. Requires `is_html=True` if the body contains HTML. All common file types including PNG, JPG, PDF, MP4, etc. are supported as attachments. Gmail API limits total message size to \~25 MB after base64 encoding. To reply in an existing thread, use GMAIL\_REPLY\_TO\_THREAD instead. No scheduled send support; enforce timing externally. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cc` | array | | `["manager@example.com","teamlead@example.com"]` | Carbon Copy (CC) recipients' email addresses. At least one of 'to'/'recipient\_email', 'cc', or 'bcc' must be provided. | | `bcc` | array | | `["auditor@example.com"]` | Blind Carbon Copy (BCC) recipients' email addresses. At least one of 'to'/'recipient\_email', 'cc', or 'bcc' must be provided. | | `body` | string | | `"Hello team, let's discuss the project updates tomorrow."` | 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`. | | `is_html` | boolean | | — | Set to `True` if the email body contains HTML tags. | | `subject` | string | | `"Project Update Meeting"` | Subject line of the email. Either subject or body must be provided for the email to be sent. | | `user_id` | string | | `"user@example.com"` | User's email address; the literal 'me' refers to the authenticated user. | | `attachment` | — | | `{"name":"report.pdf","s3key":"uploads/abc123.pdf","mimetype":"application/pdf"}` | 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. Must include valid name, mimetype (e.g., 'application/pdf'), and s3key obtained from a prior upload/download response — local paths or guessed keys cause 404 HeadObject errors. | | `from_email` | string | | `"alias@example.com"` | Sender email address for the 'From' header. Use this to send from a verified alias configured in Gmail's 'Send mail as' settings. When not provided, the authenticated user's primary email address is used. The alias must be verified in Gmail settings before use. | | `recipient_email` | string | | `"john@doe.com"` | 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. | | `extra_recipients` | array | | `["jane.doe@example.com","support@example.com"]` | Additional 'To' recipients' email addresses (not Cc or Bcc). Should only be used if recipient\_email is also provided. | *** ### Gmail Settings Get Imap Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------- | ------ | :------: | ------- | -------------------------------------------------------------------------------------- | | `user_id` | string | | `"me"` | The user's email address or the special value 'me' to indicate the authenticated user. | *** ### Gmail Settings Get Pop Integration name: **GMAIL\_SETTINGS\_GET\_POP** Tool to retrieve POP settings for a Gmail account. Use when you need to check the current POP configuration including access window and message disposition. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------- | ------ | :------: | ------- | ------------------------------------------------------------------------------------------------ | | `user_id` | string | | `"me"` | The user's email address. The special value 'me' can be used to indicate the authenticated user. | *** ### Gmail Settings Send As Get Integration name: **GMAIL\_SETTINGS\_SEND\_AS\_GET** Tool 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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------------- | ------ | :------: | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | string | | `"me"` | 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 | ✅ | `"alias@example.com"` | The send-as alias email address to retrieve. This is the email address that appears in the 'From:' header. | *** ### Gmail Stop Watch Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------- | ------ | :------: | ------- | ------------------------------------------------------------------------------------------------ | | `user_id` | string | | `"me"` | The user's email address. The special value 'me' can be used to indicate the authenticated user. | *** ### Gmail Untrash Message Integration name: **GMAIL\_UNTRASH\_MESSAGE** Tool to remove a message from trash in Gmail. Use when you need to restore a previously trashed email message. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------ | ------ | :------: | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | string | | `"user@example.com"` | User's email address or 'me' for the authenticated user. | | `message_id` | string | ✅ | `"1875f42779f726f2"` | 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. | *** ### Gmail Untrash Thread Integration name: **GMAIL\_UNTRASH\_THREAD** Tool to remove a thread from trash in Gmail. Use when you need to restore a deleted thread and its messages. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ----------- | ------ | :------: | -------------------- | ------------------------------------------------------------------------------------------------ | | `user_id` | string | | `"me"` | The user's email address. The special value 'me' can be used to indicate the authenticated user. | | `thread_id` | string | ✅ | `"19c8e0e93a7aa8ba"` | The ID of the thread to remove from trash. | *** ### Gmail Update Draft Integration name: **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. All fields are optional; if not provided, you should provide complete draft content to avoid data loss. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cc` | array | | `["cc.recipient1@example.com","CC User "]` | Carbon Copy (CC) recipients' email addresses. Each must be a valid email address or display name format. | | `bcc` | array | | `["bcc.recipient@example.com","BCC User "]` | Blind Carbon Copy (BCC) recipients' email addresses. Each must be a valid email address or display name format. | | `body` | string | | `"Hello Team,\n\nPlease find the attached report.\n\nBest regards"` | 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'. | | `is_html` | boolean | | `true` |

Set to True if body is already formatted HTML. When False, plain text newlines are auto-converted to
tags.

| | `subject` | string | | `"Project Update Q3"` | Email subject line. If not provided, previous subject is preserved. | | `user_id` | string | | `"me"` | User's email address or 'me' for the authenticated user. | | `draft_id` | string | ✅ | `"r-8388446164079304564"` | 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 | | `"17f45ec49a9c3f1b"` | ID of an existing Gmail thread. If provided, the draft will be part of this thread. | | `attachment` | — | | `{"name":"report.pdf","s3key":"uploads/abc123.pdf","mimetype":"application/pdf"}` | File(s) to attach to the draft. Accepts a single file or a list of files. Replaces any existing attachments. | | `recipient_email` | string | | `"john.doe@example.com"` | Primary recipient's email address. Must be a valid email address (e.g., '') or display name format (e.g., 'John Doe '). Optional - if not provided, previous recipients are preserved. | | `extra_recipients` | array | | `["jane.doe@example.com","Jane Doe "]` | 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. | *** ### Gmail Update Imap Settings Integration name: **GMAIL\_UPDATE\_IMAP\_SETTINGS** Tool 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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ----------------- | ------- | :------: | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | boolean | | — | Whether IMAP is enabled for the account. | | `user_id` | string | | `"me"` | The user's email address. The special value 'me' can be used to indicate the authenticated user. | | `autoExpunge` | 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. | | `maxFolderSize` | 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. | | `expungeBehavior` | string | | — | 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). | *** ### Gmail Update Label Integration name: **GMAIL\_UPDATE\_LABEL** Tool to update the properties of an existing Gmail label. Use when you need to modify label name, visibility settings, or color. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ----------------------- | ------ | :------: | ---------------------- | ------------------------------------------------------------------------------------------------ | | `id` | string | ✅ | `"Label_10"` | The ID of the label to update. | | `name` | string | | `"Updated Label Name"` | The display name of the label. | | `color` | object | | — | Color settings for the label. Both backgroundColor and textColor must be provided together. | | `userId` | string | | `"me"` | The user's email address. The special value `me` can be used to indicate the authenticated user. | | `labelListVisibility` | string | | `"labelShow"` | Visibility of the label in the label list (Gmail sidebar). | | `messageListVisibility` | string | | `"show"` | Visibility of messages with this label in the message list. | *** ### Gmail Update Language Settings Integration name: **GMAIL\_UPDATE\_LANGUAGE\_SETTINGS** Tool 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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------ | :------: | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | string | | `"me"` | 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 | ✅ | `"en"` | 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. | *** ### Gmail Update Pop Settings Integration name: **GMAIL\_UPDATE\_POP\_SETTINGS** Tool to update POP settings for a Gmail account. Use when you need to configure POP access window or message disposition behavior. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | --------------- | ------ | :------: | ---------------- | ------------------------------------------------------------------------------------------------ | | `user_id` | string | | `"me"` | The user's email address. The special value 'me' can be used to indicate the authenticated user. | | `disposition` | string | | `"leaveInInbox"` | The action that will be executed on a message after it has been fetched via POP. | | `access_window` | string | | `"allMail"` | The range of messages which are accessible via POP. | *** ### Gmail Update Send As Integration name: **GMAIL\_UPDATE\_SEND\_AS** Tool to update a send-as alias for a Gmail user. Use when you need to modify display name, signature, reply-to address, or SMTP settings for a send-as email address. Gmail sanitizes HTML signatures before saving. Addresses other than the primary can only be updated by service accounts with domain-wide authority. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ------------------ | ------- | :------: | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | string | | `"me"` | 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 | | — | SMTP relay configuration for the send-as alias. | | `signature` | string | | — | Optional HTML signature for messages composed with this alias in Gmail web UI. Gmail sanitizes HTML before saving. Only added to new emails. | | `is_default` | 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. | | `display_name` | 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. | | `send_as_email` | string | ✅ | `"alias@example.com"` | The send-as alias email address to update. This is the email address that appears in the 'From:' header. | | `treat_as_alias` | boolean | | — | Whether Gmail treats this address as an alias for the user's primary email. Only applies to custom from aliases. | | `reply_to_address` | string | | — | Optional email address for 'Reply-To:' header. Gmail omits header if empty. | *** ### Gmail Update User Attributes Values Integration name: **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. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | -------------- | ------ | :------: | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `userId` | string | ✅ | `"test-user-456"` | The unique identifier of the user whose attributes to update. | | `attributes` | object | ✅ | `{"role":"developer","department":"engineering"}` | A dictionary of attribute key-value pairs to set for the user. Values can be strings, numbers, booleans, arrays, or nested objects. These will shadow any SAML values for the same keys. | | `resourceId` | string | ✅ | `"test-org-123"` | The unique identifier of the resource. For organizations, this is the organization ID. | | `resourceType` | string | ✅ | `"organization"` | The type of resource that scopes the user attributes (e.g., 'organization' or 'project'). | *** ### Gmail Update Vacation Settings Integration name: **GMAIL\_UPDATE\_VACATION\_SETTINGS** Tool to update vacation responder settings for a Gmail user. Use when you need to configure out-of-office auto-replies. #### Parameters Your Toolhouse AI worker will automatically pass these parameters as input when the tool is called. | Parameter | Type | Required | Example | Description | | ----------------------- | ------- | :------: | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `userId` | string | | `"me"` | The user's email address. The special value 'me' can be used to indicate the authenticated user. | | `endTime` | 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. | | `startTime` | 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. | | `enableAutoReply` | boolean | | — | Flag that controls whether Gmail automatically replies to messages. | | `responseSubject` | 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. | | `responseBodyHtml` | 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. | | `restrictToDomain` | 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. | | `restrictToContacts` | boolean | | — | Flag that determines whether responses are sent to recipients who are not in the user's list of contacts. | | `responseBodyPlainText` | 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. | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.toolhouse.ai/toolhouse/integrations/gmail.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.