---
name: gmail
label: Gmail
description: Read Gmail messages, threads, and labels using the connected Google account. Use this tool to check emails, search for specific messages, read email content, list labels, or get mailbox profile info. Requires the user to have connected their Google account in Settings → Integrations.
language: typescript
inputs:
  action:
    type: string
    description: "Action to perform: list_messages, get_message, list_labels, get_thread, get_profile, sync_inbox"
  query:
    type: string
    description: "Gmail search query for list_messages (e.g. 'is:unread', 'from:user@example.com', 'subject:invoice after:2024/01/01')"
    optional: true
  message_id:
    type: string
    description: Message ID for get_message
    optional: true
  thread_id:
    type: string
    description: Thread ID for get_thread
    optional: true
  max_results:
    type: string
    description: Maximum number of results for list actions (default 10, max 50)
    optional: true
  output_dir:
    type: string
    description: Directory path to save email files (for sync_inbox action)
    optional: true
---

# Gmail Tool

Read-only access to the user's Gmail account via the Gmail REST API.

## Available Actions

- **list_messages**: List or search messages. Use `query` for Gmail search syntax.
- **get_message**: Get full message content by `message_id`.
- **list_labels**: List all Gmail labels with message counts.
- **get_thread**: Get all messages in a thread by `thread_id`.
- **get_profile**: Get the user's Gmail profile info.
- **sync_inbox**: Bulk-download emails to disk. Requires `output_dir`. Use `query` to filter (e.g. `after:2026/02/01 before:2026/03/01`). Handles pagination internally, saves each email as a markdown file, skips already-saved messages. Returns only a summary count — does NOT flood context with email bodies.

## Query Syntax

Gmail search operators for the `query` parameter:
- `is:unread`, `is:read`, `is:starred`
- `from:email@example.com`, `to:email@example.com`
- `subject:"search term"`, `has:attachment`
- `after:YYYY/MM/DD`, `before:YYYY/MM/DD`
- `in:inbox`, `in:sent`, `in:trash`
- `larger:1M`, `smaller:100K`
- Combine with AND, OR, - (NOT)

## Scope

This tool has **read-only** access (gmail.readonly scope). It cannot send, modify, or delete messages.