> This page is for Agent Handler.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Gmail

**Authentication:** OAuth. See [Magic Link](/merge-agent-handler/features/magic-link) for the runtime auth flow, or [Application credentials](/merge-agent-handler/admin-setup/add-oauth-credentials) to bring your own OAuth app.

## Sample use cases

* Find every email from contacts at our top-10 accounts in the last 7 days that I haven't replied to.
* Draft a follow-up reply to the latest message from `customer@acme.com` thanking them for the call.
* Search for emails containing `invoice` from this month and forward them to accounting\@.

## Available Tools

#### get\_attachment

Download attachment data from a message by attachment ID. Returns binary data (base64url encoded), filename, MIME type, and size.

#### list\_drafts

List all draft messages with pagination. Returns draft references with ID and snippet. Use get\_draft for complete details.

#### get\_draft

Retrieve complete details of a specific draft by ID including message content, headers, recipients, and metadata.

#### create\_draft

Create a new draft message with recipients, subject, and body. Supports HTML, CC/BCC, attachments, and threading. Returns draft with ID.

#### update\_draft

Update an existing draft by replacing its content. Completely replaces draft's message content. Returns updated draft.

#### delete\_draft

Permanently delete a draft. Cannot be undone. Draft and content are permanently removed.

#### send\_draft

Send an existing draft immediately. Draft is sent as email and automatically deleted from drafts. Returns sent message with ID.

#### list\_labels

List all labels including system and custom labels. Returns name, type, visibility, message counts, and colors.

#### get\_label

Retrieve detailed information about a specific label by ID including name, type, visibility, message counts, and colors.

#### create\_label

Create a new custom label for organizing messages. Specify name, visibility settings, and optional colors. Returns created label with ID.

#### update\_label

Update an existing label's properties including name, visibility, and colors. Cannot modify system labels, only custom labels.

#### delete\_label

Permanently delete a custom label. Removes label from all messages. Cannot delete system labels. Cannot be undone.

#### list\_messages

List messages with search, filtering, and pagination. Supports Gmail query syntax (from:, to:, subject:, is:unread, etc.). Returns message references only.

#### get\_message

Retrieve complete message details by ID including headers, body, attachments, labels, and metadata. Format options control detail level.

#### send\_message

Send a new email with recipients, subject, and body. Supports HTML, CC/BCC, attachments, and threading. Returns sent message with ID and thread ID.

#### modify\_message\_labels

Add or remove labels from a message. Supports up to 100 label additions/removals per operation. Use system or custom label IDs.

#### delete\_message

Move message to TRASH (soft delete). Recoverable for 30 days. Message gets TRASH label and is removed from other folders.

#### batch\_delete\_messages

Move multiple messages to trash in a single batch operation. More efficient than individual deletes.

#### batch\_modify\_messages

Modify labels on multiple messages in a batch operation. Supports up to 100 label additions/removals. More efficient than individual modifications.

#### list\_threads

List conversation threads with search, filtering, and pagination. Supports Gmail query syntax. Returns thread references with ID and snippet.

#### get\_thread

Retrieve a complete conversation thread by ID including all messages in chronological order. Format options control detail level.

#### modify\_thread\_labels

Add or remove labels from all messages in a thread simultaneously. Supports up to 100 label additions/removals. More efficient than modifying individual messages.

#### delete\_thread

Move all messages in a thread to TRASH (soft delete). Recoverable for 30 days. More efficient than deleting individual messages.