---
title: "Gmail"
description: "Reference for the Tracecat Gmail integration: registered actions, required secrets, expected inputs, and example workflow usage."
---

{/* Auto-generated by scripts/generate_tool_docs.py; do not edit by hand. */}
## 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 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>
