> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracecat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gmail

> Reference for the Tracecat Gmail integration: registered actions, required secrets, expected inputs, and example workflow usage.

## Batch delete messages

Action ID: `tools.gmail.batch_delete_messages`

Deletes many messages by message ID. Provides no guarantees that messages were not already deleted or even existed at all. Requires the `https://mail.google.com/` scope, which is not in the Gmail provider defaults: add it to the integration's scopes before connecting, or delegate it to the service account.

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/batchDelete](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/batchDelete)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="ids" type="array[string]" required>
  The IDs of the messages to delete.
</ParamField>

<ParamField path="user_id" type="string">
  The user's email address. The special value `me` can be used to indicate the authenticated user.

  Default: `"me"`.
</ParamField>

## Batch modify messages

Action ID: `tools.gmail.batch_modify_messages`

Modifies the labels on the specified messages.

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/batchModify](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/batchModify)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="ids" type="array[string]" required>
  The IDs of the messages to modify. There is a limit of 1000 ids per request.
</ParamField>

<ParamField path="add_label_ids" type="array[string] | null">
  A list of label IDs to add to messages.

  Default: `null`.
</ParamField>

<ParamField path="remove_label_ids" type="array[string] | null">
  A list of label IDs to remove from messages.

  Default: `null`.
</ParamField>

<ParamField path="user_id" type="string">
  The user's email address. The special value `me` can be used to indicate the authenticated user.

  Default: `"me"`.
</ParamField>

## Create draft

Action ID: `tools.gmail.create_draft`

Creates a new draft with the DRAFT label. The RFC 2822 message is assembled from the inputs and base64url-encoded before it is sent.

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.drafts/create](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.drafts/create)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="subject" type="string" required>
  Subject line of the message.
</ParamField>

<ParamField path="to" type="string" required>
  Comma-separated list of recipient email addresses for the `To` header.
</ParamField>

<ParamField path="bcc" type="string | null">
  Comma-separated list of recipient email addresses for the `Bcc` header.

  Default: `null`.
</ParamField>

<ParamField path="body_html" type="string | null">
  HTML body of the message. Added as an alternative part alongside the plain text body.

  Default: `null`.
</ParamField>

<ParamField path="body_text" type="string | null">
  Plain text body of the message.

  Default: `null`.
</ParamField>

<ParamField path="cc" type="string | null">
  Comma-separated list of recipient email addresses for the `Cc` header.

  Default: `null`.
</ParamField>

<ParamField path="in_reply_to" type="string | null">
  The `Message-ID` header value of the message being replied to. Sets the `In-Reply-To` and `References` headers.

  Default: `null`.
</ParamField>

<ParamField path="reply_to" type="string | null">
  Email address for the `Reply-To` header.

  Default: `null`.
</ParamField>

<ParamField path="thread_id" type="string | null">
  The ID of the thread the message belongs to. To add a message to a thread the `References` and `In-Reply-To` headers must be set in compliance with the RFC 2822 standard, and the `Subject` headers must match.

  Default: `null`.
</ParamField>

<ParamField path="user_id" type="string">
  The user's email address. The special value `me` can be used to indicate the authenticated user.

  Default: `"me"`.
</ParamField>

## Create label

Action ID: `tools.gmail.create_label`

Creates a new label.

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.labels/create](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.labels/create)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="body" type="object" required>
  Label resource. See [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.labels](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.labels). Fields: name (the display name of the label), labelListVisibility (the visibility of the label in the label list in the Gmail web interface: labelShow, labelShowIfUnread, labelHide), messageListVisibility (the visibility of messages with this label in the message list in the Gmail web interface: show, hide), and color (an object with textColor and backgroundColor, settable on user labels only).
</ParamField>

<ParamField path="user_id" type="string">
  The user's email address. The special value `me` can be used to indicate the authenticated user.

  Default: `"me"`.
</ParamField>

## Delete draft

Action ID: `tools.gmail.delete_draft`

Immediately and permanently deletes the specified draft. Does not simply trash it.

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.drafts/delete](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.drafts/delete)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="id" type="string" required>
  The ID of the draft to delete.
</ParamField>

<ParamField path="user_id" type="string">
  The user's email address. The special value `me` can be used to indicate the authenticated user.

  Default: `"me"`.
</ParamField>

## Delete label

Action ID: `tools.gmail.delete_label`

Immediately and permanently deletes the specified label and removes it from any messages and threads that it is applied to.

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.labels/delete](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.labels/delete)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="id" type="string" required>
  The ID of the label to delete.
</ParamField>

<ParamField path="user_id" type="string">
  The user's email address. The special value `me` can be used to indicate the authenticated user.

  Default: `"me"`.
</ParamField>

## Delete message

Action ID: `tools.gmail.delete_message`

Immediately and permanently deletes the specified message. This operation cannot be undone. Prefer messages.trash instead. Requires the `https://mail.google.com/` scope, which is not in the Gmail provider defaults: add it to the integration's scopes before connecting, or delegate it to the service account.

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/delete](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/delete)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="id" type="string" required>
  The ID of the message to delete.
</ParamField>

<ParamField path="user_id" type="string">
  The user's email address. The special value `me` can be used to indicate the authenticated user.

  Default: `"me"`.
</ParamField>

## Delete thread

Action ID: `tools.gmail.delete_thread`

Immediately and permanently deletes the specified thread. Any messages that belong to the thread are also deleted. This operation cannot be undone. Prefer threads.trash instead. Requires the `https://mail.google.com/` scope, which is not in the Gmail provider defaults: add it to the integration's scopes before connecting, or delegate it to the service account.

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.threads/delete](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.threads/delete)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="id" type="string" required>
  ID of the Thread to delete.
</ParamField>

<ParamField path="user_id" type="string">
  The user's email address. The special value `me` can be used to indicate the authenticated user.

  Default: `"me"`.
</ParamField>

## Get draft

Action ID: `tools.gmail.get_draft`

Gets the specified draft.

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.drafts/get](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.drafts/get)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="id" type="string" required>
  The ID of the draft to retrieve.
</ParamField>

<ParamField path="format" type="string | null">
  The format to return the draft in. Allowed values: minimal (only the message ID and labels), full (the full message data with the body parsed in the payload field), raw (the full message data with the body in the raw field as a base64url encoded string), metadata (only the message ID, labels, and headers). Defaults to full.

  Default: `null`.
</ParamField>

<ParamField path="user_id" type="string">
  The user's email address. The special value `me` can be used to indicate the authenticated user.

  Default: `"me"`.
</ParamField>

## Get Gmail attachment

Action ID: `tools.gmail.get_attachment`

Download an attachment from a Gmail message

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages.attachments/get](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages.attachments/get)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="attachment_id" type="string" required>
  The attachment ID to retrieve
</ParamField>

<ParamField path="message_id" type="string" required>
  The message ID containing the attachment
</ParamField>

<ParamField path="user_id" type="string">
  User ID or 'me' for authenticated user

  Default: `"me"`.
</ParamField>

## Get Gmail message

Action ID: `tools.gmail.get_message`

Get full content of a Gmail message by ID

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/get](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/get)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="message_id" type="string" required>
  The message ID to retrieve
</ParamField>

<ParamField path="format" type="string">
  Format: 'full' (complete), 'metadata' (headers only), 'minimal' (IDs only), 'raw' (RFC 2822)

  Default: `"full"`.
</ParamField>

<ParamField path="user_id" type="string">
  User ID or 'me' for authenticated user

  Default: `"me"`.
</ParamField>

## Get Gmail message headers

Action ID: `tools.gmail.get_message_headers`

Get only headers of a Gmail message (faster than full message)

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/get](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/get)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="message_id" type="string" required>
  The message ID to retrieve headers for
</ParamField>

<ParamField path="metadata_headers" type="array[string] | null">
  Specific headers to return (e.g., \['From', 'To', 'Subject']). If not specified, returns all headers.

  Default: `null`.
</ParamField>

<ParamField path="user_id" type="string">
  User ID or 'me' for authenticated user

  Default: `"me"`.
</ParamField>

## Get Gmail thread

Action ID: `tools.gmail.get_thread`

Get all messages in an email thread

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.threads/get](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.threads/get)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="thread_id" type="string" required>
  The thread ID to retrieve
</ParamField>

<ParamField path="format" type="string">
  Format: 'full' (complete), 'metadata' (headers only), 'minimal' (IDs only)

  Default: `"full"`.
</ParamField>

<ParamField path="user_id" type="string">
  User ID or 'me' for authenticated user

  Default: `"me"`.
</ParamField>

## Get label

Action ID: `tools.gmail.get_label`

Gets the specified label.

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.labels/get](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.labels/get)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="id" type="string" required>
  The ID of the label to retrieve.
</ParamField>

<ParamField path="user_id" type="string">
  The user's email address. The special value `me` can be used to indicate the authenticated user.

  Default: `"me"`.
</ParamField>

## Get profile

Action ID: `tools.gmail.get_profile`

Gets the current user's Gmail profile.

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users/getProfile](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users/getProfile)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="user_id" type="string">
  The user's email address. The special value `me` can be used to indicate the authenticated user.

  Default: `"me"`.
</ParamField>

## List drafts

Action ID: `tools.gmail.list_drafts`

Lists the drafts in the user's mailbox.

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.drafts/list](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.drafts/list)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="include_spam_trash" type="boolean | null">
  Include drafts from SPAM and TRASH in the results.

  Default: `null`.
</ParamField>

<ParamField path="max_results" type="integer | null">
  Maximum number of drafts to return. This field defaults to 100. The maximum allowed value for this field is 500.

  Default: `null`.
</ParamField>

<ParamField path="page_token" type="string | null">
  Page token to retrieve a specific page of results in the list.

  Default: `null`.
</ParamField>

<ParamField path="q" type="string | null">
  Only return draft messages matching the specified query. Supports the same query format as the Gmail search box.

  Default: `null`.
</ParamField>

<ParamField path="user_id" type="string">
  The user's email address. The special value `me` can be used to indicate the authenticated user.

  Default: `"me"`.
</ParamField>

## List Gmail labels

Action ID: `tools.gmail.list_labels`

List all Gmail labels for the user

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.labels/list](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.labels/list)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="user_id" type="string">
  User ID or 'me' for authenticated user

  Default: `"me"`.
</ParamField>

## List history

Action ID: `tools.gmail.list_history`

Lists the history of all changes to the given mailbox. History results are returned in chronological order (increasing historyId).

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="start_history_id" type="string" required>
  Returns history records after the specified startHistoryId. The supplied startHistoryId should be obtained from the historyId of a message, thread, or previous list response. History IDs increase chronologically but are not contiguous with random gaps in between valid IDs. Supplying an invalid or out of date startHistoryId typically returns an HTTP 404 error code. A historyId is typically valid for at least a week, but in some rare circumstances may be valid for only a few hours.
</ParamField>

<ParamField path="history_types" type="array[string] | null">
  History types to be returned by the function. Allowed values: messageAdded, messageDeleted, labelAdded, labelRemoved.

  Default: `null`.
</ParamField>

<ParamField path="label_id" type="string | null">
  Only return messages with a label matching the ID.

  Default: `null`.
</ParamField>

<ParamField path="max_results" type="integer | null">
  Maximum number of history records to return. This field defaults to 100. The maximum allowed value for this field is 500.

  Default: `null`.
</ParamField>

<ParamField path="page_token" type="string | null">
  Page token to retrieve a specific page of results in the list.

  Default: `null`.
</ParamField>

<ParamField path="user_id" type="string">
  The user's email address. The special value `me` can be used to indicate the authenticated user.

  Default: `"me"`.
</ParamField>

## List threads

Action ID: `tools.gmail.list_threads`

Lists the threads in the user's mailbox.

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.threads/list](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.threads/list)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="include_spam_trash" type="boolean | null">
  Include threads from SPAM and TRASH in the results.

  Default: `null`.
</ParamField>

<ParamField path="label_ids" type="array[string] | null">
  Only return threads with labels that match all of the specified label IDs.

  Default: `null`.
</ParamField>

<ParamField path="max_results" type="integer | null">
  Maximum number of threads to return. This field defaults to 100. The maximum allowed value for this field is 500.

  Default: `null`.
</ParamField>

<ParamField path="page_token" type="string | null">
  Page token to retrieve a specific page of results in the list.

  Default: `null`.
</ParamField>

<ParamField path="q" type="string | null">
  Only return threads matching the specified query. Supports the same query format as the Gmail search box.

  Default: `null`.
</ParamField>

<ParamField path="user_id" type="string">
  The user's email address. The special value `me` can be used to indicate the authenticated user.

  Default: `"me"`.
</ParamField>

## Modify message

Action ID: `tools.gmail.modify_message`

Modifies the labels on the specified message.

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/modify](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/modify)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="id" type="string" required>
  The ID of the message to modify.
</ParamField>

<ParamField path="add_label_ids" type="array[string] | null">
  A list of IDs of labels to add to this message. You can add up to 100 labels with each update.

  Default: `null`.
</ParamField>

<ParamField path="remove_label_ids" type="array[string] | null">
  A list of IDs of labels to remove from this message. You can remove up to 100 labels with each update.

  Default: `null`.
</ParamField>

<ParamField path="user_id" type="string">
  The user's email address. The special value `me` can be used to indicate the authenticated user.

  Default: `"me"`.
</ParamField>

## Modify thread

Action ID: `tools.gmail.modify_thread`

Modifies the labels applied to the thread. This applies to all messages in the thread.

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.threads/modify](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.threads/modify)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="id" type="string" required>
  The ID of the thread to modify.
</ParamField>

<ParamField path="add_label_ids" type="array[string] | null">
  A list of IDs of labels to add to this thread. You can add up to 100 labels with each update.

  Default: `null`.
</ParamField>

<ParamField path="remove_label_ids" type="array[string] | null">
  A list of IDs of labels to remove from this thread. You can remove up to 100 labels with each update.

  Default: `null`.
</ParamField>

<ParamField path="user_id" type="string">
  The user's email address. The special value `me` can be used to indicate the authenticated user.

  Default: `"me"`.
</ParamField>

## Patch label

Action ID: `tools.gmail.patch_label`

Patch the specified label.

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.labels/patch](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.labels/patch)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="body" type="object" required>
  Label resource. See [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.labels](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.labels). Fields: name (the display name of the label), labelListVisibility (the visibility of the label in the label list in the Gmail web interface: labelShow, labelShowIfUnread, labelHide), messageListVisibility (the visibility of messages with this label in the message list in the Gmail web interface: show, hide), and color (an object with textColor and backgroundColor, settable on user labels only).
</ParamField>

<ParamField path="id" type="string" required>
  The ID of the label to update.
</ParamField>

<ParamField path="user_id" type="string">
  The user's email address. The special value `me` can be used to indicate the authenticated user.

  Default: `"me"`.
</ParamField>

## Search Gmail messages

Action ID: `tools.gmail.search_messages`

Search Gmail messages using Gmail's powerful query syntax

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/list](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/list)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="query" type="string" required>
  Gmail search query (e.g., 'from:[suspicious@evil.com](mailto:suspicious@evil.com) has:attachment')
</ParamField>

<ParamField path="max_results" type="integer">
  Maximum number of results to return. The maximum allowed value for this field is 500.

  Default: `10`.
</ParamField>

<ParamField path="page_token" type="string | null">
  Page token for pagination

  Default: `null`.
</ParamField>

<ParamField path="user_id" type="string">
  User ID or 'me' for authenticated user

  Default: `"me"`.
</ParamField>

## Send draft

Action ID: `tools.gmail.send_draft`

Sends the specified, existing draft to the recipients in the To, Cc, and Bcc headers.

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.drafts/send](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.drafts/send)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="id" type="string" required>
  The immutable ID of the draft to send.
</ParamField>

<ParamField path="user_id" type="string">
  The user's email address. The special value `me` can be used to indicate the authenticated user.

  Default: `"me"`.
</ParamField>

## Send message

Action ID: `tools.gmail.send_message`

Sends the specified message to the recipients in the To, Cc, and Bcc headers. The RFC 2822 message is assembled from the inputs and base64url-encoded before it is sent.

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/send](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/send)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="subject" type="string" required>
  Subject line of the message.
</ParamField>

<ParamField path="to" type="string" required>
  Comma-separated list of recipient email addresses for the `To` header.
</ParamField>

<ParamField path="bcc" type="string | null">
  Comma-separated list of recipient email addresses for the `Bcc` header.

  Default: `null`.
</ParamField>

<ParamField path="body_html" type="string | null">
  HTML body of the message. Added as an alternative part alongside the plain text body.

  Default: `null`.
</ParamField>

<ParamField path="body_text" type="string | null">
  Plain text body of the message.

  Default: `null`.
</ParamField>

<ParamField path="cc" type="string | null">
  Comma-separated list of recipient email addresses for the `Cc` header.

  Default: `null`.
</ParamField>

<ParamField path="in_reply_to" type="string | null">
  The `Message-ID` header value of the message being replied to. Sets the `In-Reply-To` and `References` headers.

  Default: `null`.
</ParamField>

<ParamField path="reply_to" type="string | null">
  Email address for the `Reply-To` header.

  Default: `null`.
</ParamField>

<ParamField path="thread_id" type="string | null">
  The ID of the thread the message belongs to. To add a message to a thread the `References` and `In-Reply-To` headers must be set in compliance with the RFC 2822 standard, and the `Subject` headers must match.

  Default: `null`.
</ParamField>

<ParamField path="user_id" type="string">
  The user's email address. The special value `me` can be used to indicate the authenticated user.

  Default: `"me"`.
</ParamField>

## Trash message

Action ID: `tools.gmail.trash_message`

Moves the specified message to the trash.

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/trash](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/trash)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="id" type="string" required>
  The ID of the message to move to trash.
</ParamField>

<ParamField path="user_id" type="string">
  The user's email address. The special value `me` can be used to indicate the authenticated user.

  Default: `"me"`.
</ParamField>

## Trash thread

Action ID: `tools.gmail.trash_thread`

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

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.threads/trash](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.threads/trash)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="id" type="string" required>
  The ID of the thread to Trash.
</ParamField>

<ParamField path="user_id" type="string">
  The user's email address. The special value `me` can be used to indicate the authenticated user.

  Default: `"me"`.
</ParamField>

## Untrash message

Action ID: `tools.gmail.untrash_message`

Removes the specified message from the trash.

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/untrash](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/untrash)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="id" type="string" required>
  The ID of the message to remove from Trash.
</ParamField>

<ParamField path="user_id" type="string">
  The user's email address. The special value `me` can be used to indicate the authenticated user.

  Default: `"me"`.
</ParamField>

## Untrash thread

Action ID: `tools.gmail.untrash_thread`

Removes the specified thread from the trash. Any messages that belong to the thread are also removed from the trash.

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.threads/untrash](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.threads/untrash)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="id" type="string" required>
  The ID of the thread to remove from Trash.
</ParamField>

<ParamField path="user_id" type="string">
  The user's email address. The special value `me` can be used to indicate the authenticated user.

  Default: `"me"`.
</ParamField>

## Update draft

Action ID: `tools.gmail.update_draft`

Replaces a draft's content. The RFC 2822 message is assembled from the inputs and base64url-encoded before it is sent.

Reference: [https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.drafts/update](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.drafts/update)

### Secrets

Optional secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.
* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_SERVICE_TOKEN`.
* `google_api`: required values `GOOGLE_API_CREDENTIALS`; optional values `GOOGLE_API_SUBJECT`.

### Input fields

<ParamField path="id" type="string" required>
  The ID of the draft to update.
</ParamField>

<ParamField path="subject" type="string" required>
  Subject line of the message.
</ParamField>

<ParamField path="to" type="string" required>
  Comma-separated list of recipient email addresses for the `To` header.
</ParamField>

<ParamField path="bcc" type="string | null">
  Comma-separated list of recipient email addresses for the `Bcc` header.

  Default: `null`.
</ParamField>

<ParamField path="body_html" type="string | null">
  HTML body of the message. Added as an alternative part alongside the plain text body.

  Default: `null`.
</ParamField>

<ParamField path="body_text" type="string | null">
  Plain text body of the message.

  Default: `null`.
</ParamField>

<ParamField path="cc" type="string | null">
  Comma-separated list of recipient email addresses for the `Cc` header.

  Default: `null`.
</ParamField>

<ParamField path="in_reply_to" type="string | null">
  The `Message-ID` header value of the message being replied to. Sets the `In-Reply-To` and `References` headers.

  Default: `null`.
</ParamField>

<ParamField path="reply_to" type="string | null">
  Email address for the `Reply-To` header.

  Default: `null`.
</ParamField>

<ParamField path="thread_id" type="string | null">
  The ID of the thread the message belongs to. To add a message to a thread the `References` and `In-Reply-To` headers must be set in compliance with the RFC 2822 standard, and the `Subject` headers must match.

  Default: `null`.
</ParamField>

<ParamField path="user_id" type="string">
  The user's email address. The special value `me` can be used to indicate the authenticated user.

  Default: `"me"`.
</ParamField>