> ## 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.

## Get Gmail attachment

Action ID: `tools.gmail.get_attachment`

Download an attachment from a Gmail message.

### Secrets

Required secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.

### 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 the full content of a Gmail message.

### Secrets

Required secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.

### 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 the headers of a Gmail message.

### Secrets

Required secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.

### 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.

### Secrets

Required secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.

### 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>

## List Gmail labels

Action ID: `tools.gmail.list_labels`

List all Gmail labels for a user.

### Secrets

Required secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.

### Input fields

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

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

## Search Gmail messages

Action ID: `tools.gmail.search_messages`

Search Gmail messages using Gmail's search syntax.

### Secrets

Required secrets:

* `google_gmail_oauth`: OAuth token `GOOGLE_GMAIL_USER_TOKEN`.

### 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

  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>