# Gmail - All Email Actions

## Links

- Product page URL: https://www.agentpmt.com/marketplace/gmail-all-email-actions
- Product markdown URL: https://www.agentpmt.com/marketplace/gmail-all-email-actions?format=agent-md
- Product JSON URL: https://www.agentpmt.com/marketplace/gmail-all-email-actions?format=agent-json

## Overview

- Product ID: 69618e485d4cf4d4b6af40f0
- Vendor: Apoth3osis
- Type: connector
- Unit type: request
- Price: 500 credits
- Categories: Project Management, Automation, Sales Engagement & Outreach, Email Marketing & Campaigns, Marketing Automation, Task & Workflow Automation
- Generated at: 2026-05-30T20:28:08.274Z

### Page Description

Gmail connection that enables agents to send, read, search, and manage email through Google OAuth integration. The tool provides comprehensive email functionality including composing and sending new messages with attachments, replying to emails while maintaining thread continuity, and forwarding messages to new recipients. Agents can search and filter emails using Gmail's powerful query syntax to find specific messages by sender, subject, date, labels, or attachment status. The tool supports full email lifecycle management including reading message content with parsed headers and body text, moving messages to trash or permanently deleting them, and modifying labels to organize emails or mark them as read. Draft functionality allows agents to create, retrieve, and send draft emails for workflows requiring human review before sending. Additional capabilities include listing all available labels for organization, retrieving user profile information such as email address and message counts, and sending from custom authenticated email addresses.

### Agent Description

Gmail integration: send, read, search, reply, forward emails. Manage labels, drafts, trash. Supports attachments and custom from addresses.

## Details

### Details

Gmail connection that enables agents to send, read, search, and manage email through Google OAuth integration. The tool provides comprehensive email functionality including composing and sending new messages with attachments, replying to emails while maintaining thread continuity, and forwarding messages to new recipients. Agents can search and filter emails using Gmail's powerful query syntax to find specific messages by sender, subject, date, labels, or attachment status. The tool supports full email lifecycle management including reading message content with parsed headers and body text, moving messages to trash or permanently deleting them, and modifying labels to organize emails or mark them as read. Draft functionality allows agents to create, retrieve, and send draft emails for workflows requiring human review before sending. Additional capabilities include listing all available labels for organization, retrieving user profile information such as email address and message counts, and sending from custom authenticated email addresses.

### Actions

- `send_message` (5 credits): Send a new email. Supports plain text, HTML, attachments, CC/BCC, and custom from address (requires send-as alias).
- `reply_message` (5 credits): Reply to an existing email. The reply stays in the same thread and automatically uses the original subject and recipient.
- `forward_message` (5 credits): Forward an email to new recipients. The original message content is included automatically.
- `list_messages` (5 credits): Search and list emails. Returns message IDs and thread IDs. Use get_message to read full content.
- `get_message` (5 credits): Read the full content of an email including headers, body text, HTML, and attachment metadata.
- `trash_message` (5 credits): Move an email to the trash.
- `untrash_message` (5 credits): Restore an email from the trash back to its original location.
- `modify_labels` (5 credits): Add or remove labels from an email. Common uses: mark as read (remove UNREAD), star (add STARRED), archive (remove INBOX).
- `list_labels` (5 credits): Get all available Gmail labels (both system and user-created).
- `create_draft` (5 credits): Create a draft email that can be edited or sent later.
- `send_draft` (5 credits): Send a previously created draft email.
- `get_draft` (5 credits): Retrieve the content of a draft email.
- `delete_draft` (5 credits): Permanently delete a draft email.
- `get_profile` (5 credits): Get the authenticated user's Gmail profile including email address, total message count, and total thread count.

### Use Cases

Automated email notifications and alerts, Customer inquiry response and follow-up, Email search and retrieval for information gathering, Inbox management and organization with labels, Draft creation for human-in-the-loop email workflows, Email forwarding and delegation workflows, Reading and summarizing email content, Marking messages as read or starring important emails, Sending reports and documents as attachments, Monitoring inbox for specific senders or keywords

### Workflows Using This Tool

#### Gmail Inbox Triage to Telegram - Urgency and Intent

Sweeps your Gmail inbox for emails received in the last 24 hours, looks up each sender's prior Gmail history to classify them as existing customer, new inquiry, marketing, or automated, scores urgency, and sends a single Telegram digest containing only the high and medium urgency emails that actually need your reply. Skips marketing, no-reply notifications, and one-way confirmations.

- Page URL: https://www.agentpmt.com/agent-workflow-skills/gmail-inbox-triage-to-telegram-urgency-and-intent--6a16438899942aa48e2f1d0c
- Markdown URL: https://www.agentpmt.com/agent-workflow-skills/gmail-inbox-triage-to-telegram-urgency-and-intent--6a16438899942aa48e2f1d0c?format=agent-md
- Published: 2026-05-27T01:06:27.207Z

#### Expense Report Processor

Processes employee expense reports by accepting receipt uploads, extracting receipt data via OCR, categorizing expenses, booking them to Zoho Books with correct expense accounts, generating an expense breakdown chart, and sending the compiled report for manager approval. Streamlines the entire expense reimbursement process.

- Page URL: https://www.agentpmt.com/agent-workflow-skills/expense-report-processor
- Markdown URL: https://www.agentpmt.com/agent-workflow-skills/expense-report-processor?format=agent-md
- Published: 2026-04-19T18:29:42.593Z

#### YouTube Transcript -> Newsletter Draft (Gmail)

Fetch a YouTube transcript, extract the best insights/quotes, and create a polished newsletter draft in Gmail.

- Page URL: https://www.agentpmt.com/agent-workflow-skills/youtube-transcript-newsletter-draft-gmail
- Markdown URL: https://www.agentpmt.com/agent-workflow-skills/youtube-transcript-newsletter-draft-gmail?format=agent-md
- Published: 2026-02-19T20:11:50.002Z

#### Gmail Smart Inbox: Filter, Draft Responses, and Discord Summary

Searches Gmail for recent unread emails, cross-references senders against Google Contacts to filter out spam and automated messages, identifies important emails from real people, drafts and saves personalized responses in Gmail for each, then posts a formatted summary of all important emails and drafted responses to a Discord channel.

- Page URL: https://www.agentpmt.com/agent-workflow-skills/gmail-search-and-discord-notification
- Markdown URL: https://www.agentpmt.com/agent-workflow-skills/gmail-search-and-discord-notification?format=agent-md
- Published: 2026-02-19T19:01:06.332Z

#### Rental Property Cash Flow Analyzer

Analyzes rental property investment viability by calculating mortgage payments, computing net operating income and cash-on-cash returns, projecting cash flows, generating return visualizations, creating a comprehensive investment analysis report, and delivering it to the investor. Essential for real estate investors evaluating rental property acquisitions.

- Page URL: https://www.agentpmt.com/agent-workflow-skills/rental-property-cash-flow-analyzer
- Markdown URL: https://www.agentpmt.com/agent-workflow-skills/rental-property-cash-flow-analyzer?format=agent-md
- Published: 2026-02-18T16:43:43.406Z

#### Accounts Receivable Follow-Up

Automates collections by pulling overdue invoices from Zoho Books, calculating days overdue, drafting collection emails with appropriate urgency levels, sending reminders to customers, and tracking collection efforts in a spreadsheet. Improves cash flow by ensuring consistent follow-up on unpaid invoices.

- Page URL: https://www.agentpmt.com/agent-workflow-skills/accounts-receivable-follow-up
- Markdown URL: https://www.agentpmt.com/agent-workflow-skills/accounts-receivable-follow-up?format=agent-md
- Published: 2026-02-15T19:19:27.272Z

### Related Content

No related content is currently linked to this product.

## Integration Details

### DynamicMCP

- Setup page URL: https://www.agentpmt.com/dynamic-mcp
- Claude setup guide: https://www.agentpmt.com/dynamic-mcp?platform=claude#videos
- ChatGPT setup guide: https://www.agentpmt.com/dynamic-mcp?platform=chatgpt#videos
- Cursor setup guide: https://www.agentpmt.com/dynamic-mcp?platform=cursor#videos
- Windsurf setup guide: https://www.agentpmt.com/dynamic-mcp?platform=windsurf#videos

Use the local router for command-based MCP clients. It forwards requests to `https://api.agentpmt.com/mcp` and does not execute tools locally.

```bash
npm install -g @agentpmt/mcp-router
agentpmt-setup
```

### REST API

The live page renders cURL, Python, JavaScript, and Node.js examples. Logged-in users see those examples prefilled with their own API and budget credentials.

- Purchase endpoint: https://api.agentpmt.com/products/purchase
- Authorization format: `Bearer <base64(apiKey:budgetKey)>`

```bash
curl -X POST "https://api.agentpmt.com/products/purchase" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eW91ci1hcGkta2V5LWhlcmU6eW91ci1idWRnZXQta2V5LWhlcmU=" \
  -d '{
    "product_id": "69618e485d4cf4d4b6af40f0",
    "parameters": {
      "action": "send_message",
      "to": [],
      "subject": "example_subject"
    }
  }'
```

### Autonomous Agents

Autonomous agents can access this tool through AgentAddress credit balances or direct x402 payments. Use the Autonomous Agent API reference for endpoint shapes after choosing the access pattern below.

- Autonomous Agent API reference URL: https://www.agentpmt.com/docs/api-reference/autonomous-agents
- Autonomous Agent API reference markdown URL: https://www.agentpmt.com/docs/api-reference/autonomous-agents?format=agent-md
- Credit-Based Access Using AgentAddress: https://www.agentpmt.com/docs/autonomous-agents/credit-based-tool-usage-with-agentaddress
- AgentAddress is preferred for persistent file access, stored platform state, and maximum tool use ability across repeated calls.
- Direct x402 is for independent one-off tool calls that do not require shared files or stored platform state.
- Direct x402 public payments: USDC on Base, Arbitrum, Optimism, Polygon, and Avalanche.

### Schema

#### Credentials

These runtime credentials should be provided under `parameters._credentials` when required.

- Google OAuth (`google_oauth`, oauth_token, required)
  Help: Connect your Google account.
  Connection ID: 69616abea90ed54743f01957

#### Parameters

- Schema type: actions

```json
{
  "actions": {
    "send_message": {
      "description": "Send a new email. Supports plain text, HTML, attachments, CC/BCC, and custom from address (requires send-as alias).",
      "properties": {
        "to": {
          "type": "array",
          "description": "Recipient email addresses",
          "required": true,
          "items": {
            "type": "string"
          }
        },
        "subject": {
          "type": "string",
          "description": "Email subject line",
          "required": true
        },
        "body_text": {
          "type": "string",
          "description": "Plain text email body. Required unless body_html is provided.",
          "required": false
        },
        "body_html": {
          "type": "string",
          "description": "HTML email body. Can be used instead of or in addition to body_text.",
          "required": false
        },
        "cc": {
          "type": "array",
          "description": "CC recipients",
          "required": false,
          "items": {
            "type": "string"
          }
        },
        "bcc": {
          "type": "array",
          "description": "BCC recipients",
          "required": false,
          "items": {
            "type": "string"
          }
        },
        "from_email": {
          "type": "string",
          "description": "From address to override the default sender. Only works if a send-as alias is configured in Gmail settings.",
          "required": false
        },
        "thread_id": {
          "type": "string",
          "description": "Thread ID to add this message to an existing conversation thread",
          "required": false
        },
        "attachments": {
          "type": "array",
          "description": "File attachments. Provide public file URLs that will be fetched and attached.",
          "required": false,
          "items": {
            "type": "object",
            "properties": {
              "filename": {
                "type": "string",
                "description": "Attachment filename (e.g., 'report.pdf')",
                "required": true
              },
              "file_url": {
                "type": "string",
                "description": "Public URL to fetch the file from (must be directly accessible)",
                "required": true
              },
              "content_type": {
                "type": "string",
                "description": "MIME type (e.g., 'application/pdf'). Auto-detected if not provided.",
                "required": false,
                "default": "application/octet-stream"
              }
            }
          }
        }
      }
    },
    "reply_message": {
      "description": "Reply to an existing email. The reply stays in the same thread and automatically uses the original subject and recipient.",
      "properties": {
        "message_id": {
          "type": "string",
          "description": "Gmail message ID of the email to reply to",
          "required": true
        },
        "body_text": {
          "type": "string",
          "description": "Plain text reply body. Required unless body_html is provided.",
          "required": false
        },
        "body_html": {
          "type": "string",
          "description": "HTML reply body. Can be used instead of or in addition to body_text.",
          "required": false
        },
        "cc": {
          "type": "array",
          "description": "CC recipients",
          "required": false,
          "items": {
            "type": "string"
          }
        },
        "bcc": {
          "type": "array",
          "description": "BCC recipients",
          "required": false,
          "items": {
            "type": "string"
          }
        },
        "attachments": {
          "type": "array",
          "description": "File attachments",
          "required": false,
          "items": {
            "type": "object",
            "properties": {
              "filename": {
                "type": "string",
                "description": "Attachment filename",
                "required": true
              },
              "file_url": {
                "type": "string",
                "description": "Public URL to fetch the file from",
                "required": true
              },
              "content_type": {
                "type": "string",
                "description": "MIME type. Auto-detected if not provided.",
                "required": false,
                "default": "application/octet-stream"
              }
            }
          }
        }
      }
    },
    "forward_message": {
      "description": "Forward an email to new recipients. The original message content is included automatically.",
      "properties": {
        "message_id": {
          "type": "string",
          "description": "Gmail message ID of the email to forward",
          "required": true
        },
        "to": {
          "type": "array",
          "description": "Recipient email addresses to forward to",
          "required": true,
          "items": {
            "type": "string"
          }
        },
        "body_text": {
          "type": "string",
          "description": "Optional text to add above the forwarded content",
          "required": false
        },
        "cc": {
          "type": "array",
          "description": "CC recipients",
          "required": false,
          "items": {
            "type": "string"
          }
        },
        "bcc": {
          "type": "array",
          "description": "BCC recipients",
          "required": false,
          "items": {
            "type": "string"
          }
        },
        "attachments": {
          "type": "array",
          "description": "Additional file attachments",
          "required": false,
          "items": {
            "type": "object",
            "properties": {
              "filename": {
                "type": "string",
                "description": "Attachment filename",
                "required": true
              },
              "file_url": {
                "type": "string",
                "description": "Public URL to fetch the file from",
                "required": true
              },
              "content_type": {
                "type": "string",
                "description": "MIME type. Auto-detected if not provided.",
                "required": false,
                "default": "application/octet-stream"
              }
            }
          }
        }
      }
    },
    "list_messages": {
      "description": "Search and list emails. Returns message IDs and thread IDs. Use get_message to read full content.",
      "properties": {
        "q": {
          "type": "string",
          "description": "Gmail search query (e.g., 'is:unread', 'from:user@example.com', 'subject:meeting', 'has:attachment', 'newer_than:7d')",
          "required": false
        },
        "max_results": {
          "type": "integer",
          "description": "Maximum results to return (1-500)",
          "required": false,
          "default": 20,
          "minimum": 1,
          "maximum": 500
        },
        "label_ids": {
          "type": "array",
          "description": "Filter by these label IDs",
          "required": false,
          "items": {
            "type": "string"
          }
        },
        "page_token": {
          "type": "string",
          "description": "Pagination token from a previous list_messages response",
          "required": false
        }
      }
    },
    "get_message": {
      "description": "Read the full content of an email including headers, body text, HTML, and attachment metadata.",
      "properties": {
        "message_id": {
          "type": "string",
          "description": "Gmail message ID",
          "required": true
        },
        "message_format": {
          "type": "string",
          "description": "Message format: full (headers + body, default), metadata (headers only), minimal (IDs only)",
          "required": false,
          "default": "full",
          "enum": [
            "full",
            "metadata",
            "minimal"
          ]
        }
      }
    },
    "trash_message": {
      "description": "Move an email to the trash.",
      "properties": {
        "message_id": {
          "type": "string",
          "description": "Gmail message ID of the email to trash",
          "required": true
        }
      }
    },
    "untrash_message": {
      "description": "Restore an email from the trash back to its original location.",
      "properties": {
        "message_id": {
          "type": "string",
          "description": "Gmail message ID of the email to restore",
          "required": true
        }
      }
    },
    "modify_labels": {
      "description": "Add or remove labels from an email. Common uses: mark as read (remove UNREAD), star (add STARRED), archive (remove INBOX).",
      "properties": {
        "message_id": {
          "type": "string",
          "description": "Gmail message ID",
          "required": true
        },
        "add_label_ids": {
          "type": "array",
          "description": "Label IDs to add. Common: STARRED, IMPORTANT, UNREAD",
          "required": false,
          "items": {
            "type": "string"
          }
        },
        "remove_label_ids": {
          "type": "array",
          "description": "Label IDs to remove. Common: UNREAD (mark as read), INBOX (archive)",
          "required": false,
          "items": {
            "type": "string"
          }
        }
      }
    },
    "list_labels": {
      "description": "Get all available Gmail labels (both system and user-created)."
    },
    "create_draft": {
      "description": "Create a draft email that can be edited or sent later.",
      "properties": {
        "to": {
          "type": "array",
          "description": "Recipient email addresses",
          "required": true,
          "items": {
            "type": "string"
          }
        },
        "subject": {
          "type": "string",
          "description": "Email subject line",
          "required": true
        },
        "body_text": {
          "type": "string",
          "description": "Plain text email body. Required unless body_html is provided.",
          "required": false
        },
        "body_html": {
          "type": "string",
          "description": "HTML email body. Can be used instead of or in addition to body_text.",
          "required": false
        },
        "cc": {
          "type": "array",
          "description": "CC recipients",
          "required": false,
          "items": {
            "type": "string"
          }
        },
        "bcc": {
          "type": "array",
          "description": "BCC recipients",
          "required": false,
          "items": {
            "type": "string"
          }
        },
        "from_email": {
          "type": "string",
          "description": "From address override (requires send-as alias)",
          "required": false
        },
        "thread_id": {
          "type": "string",
          "description": "Thread ID to associate the draft with an existing conversation",
          "required": false
        },
        "attachments": {
          "type": "array",
          "description": "File attachments",
          "required": false,
          "items": {
            "type": "object",
            "properties": {
              "filename": {
                "type": "string",
                "description": "Attachment filename",
                "required": true
              },
              "file_url": {
                "type": "string",
                "description": "Public URL to fetch the file from",
                "required": true
              },
              "content_type": {
                "type": "string",
                "description": "MIME type. Auto-detected if not provided.",
                "required": false,
                "default": "application/octet-stream"
              }
            }
          }
        }
      }
    },
    "send_draft": {
      "description": "Send a previously created draft email.",
      "properties": {
        "draft_id": {
          "type": "string",
          "description": "Gmail draft ID",
          "required": true
        }
      }
    },
    "get_draft": {
      "description": "Retrieve the content of a draft email.",
      "properties": {
        "draft_id": {
          "type": "string",
          "description": "Gmail draft ID",
          "required": true
        },
        "message_format": {
          "type": "string",
          "description": "Message format: full (default), metadata, minimal",
          "required": false,
          "default": "full",
          "enum": [
            "full",
            "metadata",
            "minimal"
          ]
        }
      }
    },
    "delete_draft": {
      "description": "Permanently delete a draft email.",
      "properties": {
        "draft_id": {
          "type": "string",
          "description": "Gmail draft ID to delete",
          "required": true
        }
      }
    },
    "get_profile": {
      "description": "Get the authenticated user's Gmail profile including email address, total message count, and total thread count."
    }
  },
  "properties": {
    "action": {
      "type": "string",
      "description": "Action to perform. Use get_instructions for documentation. Core actions: send_message (send new email), reply_message (reply to email), forward_message (forward email), list_messages (search/list emails), get_message (read email), trash_message (move to trash), modify_labels (add/remove labels), list_labels (get all labels), create_draft (create draft), send_draft (send draft), get_profile (get user info)",
      "required": true,
      "enum": [
        "get_instructions",
        "send_message",
        "reply_message",
        "forward_message",
        "list_messages",
        "get_message",
        "trash_message",
        "untrash_message",
        "modify_labels",
        "list_labels",
        "create_draft",
        "send_draft",
        "get_draft",
        "delete_draft",
        "get_profile"
      ]
    },
    "to": {
      "type": "array",
      "description": "Recipient email addresses. Required for: send_message, forward_message, create_draft",
      "required": false,
      "items": {
        "type": "string"
      }
    },
    "subject": {
      "type": "string",
      "description": "Email subject line. Required for: send_message, create_draft",
      "required": false
    },
    "from_email": {
      "type": "string",
      "description": "From address to override the default sender (optional). Only works if you have configured send-as alias in Gmail settings.",
      "required": false
    },
    "body_text": {
      "type": "string",
      "description": "Plain text email body. Required for: send_message, reply_message, create_draft (unless body_html provided)",
      "required": false
    },
    "body_html": {
      "type": "string",
      "description": "HTML email body. Can be used instead of or in addition to body_text",
      "required": false
    },
    "cc": {
      "type": "array",
      "description": "CC recipients",
      "required": false,
      "items": {
        "type": "string"
      }
    },
    "bcc": {
      "type": "array",
      "description": "BCC recipients",
      "required": false,
      "items": {
        "type": "string"
      }
    },
    "message_id": {
      "type": "string",
      "description": "Gmail message ID. Required for: reply_message, forward_message, get_message, trash_message, untrash_message, modify_labels",
      "required": false
    },
    "draft_id": {
      "type": "string",
      "description": "Gmail draft ID. Required for: send_draft, get_draft, delete_draft",
      "required": false
    },
    "thread_id": {
      "type": "string",
      "description": "Thread ID to continue an email thread",
      "required": false
    },
    "q": {
      "type": "string",
      "description": "Gmail search query for list_messages. Examples: is:unread, from:user@example.com, subject:meeting, has:attachment, newer_than:7d",
      "required": false
    },
    "max_results": {
      "type": "integer",
      "description": "Maximum results for list_messages (1-500)",
      "required": false,
      "default": 20,
      "minimum": 1,
      "maximum": 500
    },
    "page_token": {
      "type": "string",
      "description": "Pagination token from previous list_messages response",
      "required": false
    },
    "label_ids": {
      "type": "array",
      "description": "Filter list_messages by these label IDs",
      "required": false,
      "items": {
        "type": "string"
      }
    },
    "add_label_ids": {
      "type": "array",
      "description": "Label IDs to add for modify_labels action. Common: STARRED, IMPORTANT, UNREAD",
      "required": false,
      "items": {
        "type": "string"
      }
    },
    "remove_label_ids": {
      "type": "array",
      "description": "Label IDs to remove for modify_labels action. Common: UNREAD (mark as read), INBOX (archive)",
      "required": false,
      "items": {
        "type": "string"
      }
    },
    "format": {
      "type": "string",
      "description": "Message format for get_message: full (default, headers+body), metadata (headers only), minimal (IDs only)",
      "required": false,
      "default": "full",
      "enum": [
        "full",
        "metadata",
        "minimal"
      ]
    },
    "attachments": {
      "type": "array",
      "description": "Email attachments for send_message/create_draft. Provide public file URLs that will be fetched and attached.",
      "required": false,
      "items": {
        "type": "object",
        "properties": {
          "filename": {
            "type": "string",
            "description": "Attachment filename (e.g., 'report.pdf', 'image.png')"
          },
          "file_url": {
            "type": "string",
            "description": "Public URL to fetch the file from (must be directly accessible)"
          },
          "content_type": {
            "type": "string",
            "description": "MIME type (e.g., 'application/pdf'). Auto-detected from URL response if not provided.",
            "default": "application/octet-stream"
          }
        }
      }
    }
  }
}
```

### Usage Instructions

# Gmail - All Email Actions

Complete Gmail management: send, reply, forward, search, read, trash, label, and draft emails.

## Actions

### send_message
Send a new email.

**Required:** `to` (array of email addresses), `subject`, `body_text` or `body_html`
**Optional:** `cc`, `bcc`, `from_email` (requires send-as alias configured in Gmail), `body_html`, `attachments`, `thread_id`

```json
{
  "action": "send_message",
  "to": ["recipient@example.com"],
  "subject": "Project Update",
  "body_text": "Hi, here is the latest update on the project.",
  "cc": ["manager@example.com"]
}
```

**With attachment:**
```json
{
  "action": "send_message",
  "to": ["team@example.com"],
  "subject": "Monthly Report",
  "body_text": "Please find the report attached.",
  "attachments": [
    {
      "filename": "report.pdf",
      "file_url": "https://example.com/files/report.pdf",
      "content_type": "application/pdf"
    }
  ]
}
```

### reply_message
Reply to an existing email. The reply stays in the same thread and automatically uses the original subject and recipient.

**Required:** `message_id`, `body_text` or `body_html`
**Optional:** `cc`, `bcc`, `attachments`

```json
{
  "action": "reply_message",
  "message_id": "18a1b2c3d4e5f6g7",
  "body_text": "Thanks for the update. I'll review this by Friday."
}
```

### forward_message
Forward an email to new recipients. The original message content is included automatically.

**Required:** `message_id`, `to`
**Optional:** `body_text` (added above the forwarded content), `cc`, `bcc`, `attachments`

```json
{
  "action": "forward_message",
  "message_id": "18a1b2c3d4e5f6g7",
  "to": ["colleague@example.com"],
  "body_text": "FYI - see the message below."
}
```

### list_messages
Search and list emails. Returns message IDs and thread IDs. Use `get_message` to read full content.

**Required:** none
**Optional:** `q` (Gmail search query), `max_results` (1-500, default 20), `label_ids`, `page_token`

```json
{
  "action": "list_messages",
  "q": "is:unread from:boss@example.com",
  "max_results": 10
}
```

**Common search queries:**
- `is:unread` - unread messages
- `from:user@example.com` - from a specific sender
- `subject:meeting` - subject contains "meeting"
- `has:attachment` - messages with attachments
- `newer_than:7d` - from the last 7 days
- `older_than:30d` - older than 30 days
- `in:sent` - sent messages
- `label:work` - messages with a specific label

### get_message
Read the full content of an email including headers, body, and attachment metadata.

**Required:** `message_id`
**Optional:** `format` - `full` (default, headers + body), `metadata` (headers only), `minimal` (IDs only)

```json
{
  "action": "get_message",
  "message_id": "18a1b2c3d4e5f6g7",
  "format": "full"
}
```

### trash_message
Move an email to the trash.

**Required:** `message_id`

```json
{
  "action": "trash_message",
  "message_id": "18a1b2c3d4e5f6g7"
}
```

### untrash_message
Restore an email from the trash back to its original location.

**Required:** `message_id`

```json
{
  "action": "untrash_message",
  "message_id": "18a1b2c3d4e5f6g7"
}
```

### modify_labels
Add or remove labels from an email. Use `list_labels` first to find available label IDs.

**Required:** `message_id`, at least one of `add_label_ids` or `remove_label_ids`

```json
{
  "action": "modify_labels",
  "message_id": "18a1b2c3d4e5f6g7",
  "add_label_ids": ["STARRED"],
  "remove_label_ids": ["UNREAD"]
}
```

**Common label IDs:** `INBOX`, `SENT`, `TRASH`, `DRAFT`, `SPAM`, `STARRED`, `IMPORTANT`, `UNREAD`, `CATEGORY_PERSONAL`, `CATEGORY_SOCIAL`, `CATEGORY_PROMOTIONS`

**Useful patterns:**
- Mark as read: `remove_label_ids: ["UNREAD"]`
- Mark as unread: `add_label_ids: ["UNREAD"]`
- Archive: `remove_label_ids: ["INBOX"]`
- Star: `add_label_ids: ["STARRED"]`

### list_labels
Get all available labels (system and user-created).

**Required:** none

```json
{
  "action": "list_labels"
}
```

### create_draft
Create a draft email that can be edited or sent later.

**Required:** `to`, `subject`, `body_text` or `body_html`
**Optional:** `cc`, `bcc`, `from_email`, `body_html`, `attachments`, `thread_id`

```json
{
  "action": "create_draft",
  "to": ["client@example.com"],
  "subject": "Proposal Draft",
  "body_html": "<h1>Proposal</h1><p>Here are the details...</p>"
}
```

### send_draft
Send a previously created draft.

**Required:** `draft_id`

```json
{
  "action": "send_draft",
  "draft_id": "r123456789"
}
```

### get_draft
Retrieve the content of a draft.

**Required:** `draft_id`
**Optional:** `format` - `full` (default), `metadata`, `minimal`

```json
{
  "action": "get_draft",
  "draft_id": "r123456789"
}
```

### delete_draft
Permanently delete a draft.

**Required:** `draft_id`

```json
{
  "action": "delete_draft",
  "draft_id": "r123456789"
}
```

### get_profile
Get the authenticated user's Gmail profile including email address and message counts.

**Required:** none

```json
{
  "action": "get_profile"
}
```

## Common Workflows

**Check and read unread emails:**
1. `list_messages` with `q: "is:unread"` to get message IDs
2. `get_message` for each message ID to read content
3. `modify_labels` with `remove_label_ids: ["UNREAD"]` to mark as read

**Send email with review:**
1. `create_draft` to compose the email
2. `get_draft` to review content
3. `send_draft` to send, or `delete_draft` to discard

**Reply to a conversation:**
1. `list_messages` with a search query to find the thread
2. `get_message` to read the message you want to reply to
3. `reply_message` with the message_id and your response

**Organize inbox:**
1. `list_messages` to find messages
2. `list_labels` to see available labels
3. `modify_labels` to apply labels, archive, or star messages

## Important Notes

- **Attachments:** Provide public URLs for file attachments. The files are fetched and attached automatically. Content type is auto-detected if not specified.
- **HTML emails:** You can send both `body_text` and `body_html` together. Recipients who support HTML will see the rich version; others see plain text.
- **Search syntax:** The `q` parameter uses standard Gmail search operators. Combine multiple operators for precise filtering (e.g., `from:alice@example.com newer_than:7d has:attachment`).
- **Pagination:** When `list_messages` returns a `next_page_token`, pass it as `page_token` in the next request to get more results.
- **From address:** The `from_email` field only works if you have configured a send-as alias in Gmail settings.
- **Thread management:** Use `thread_id` with `send_message` or `create_draft` to add a message to an existing conversation thread.

### Frequently Asked Questions

#### How do I connect this tool to an external agent?

- Page URL: https://www.agentpmt.com/faq
- Markdown URL: https://www.agentpmt.com/faq?format=agent-md

You can install the local MCP server by opening a terminal and running:

```
npm install -g @agentpmt/mcp-router
agentpmt-setup
```

This will connect you to local agents like Claude Code, Windsurf, Grok Build, Cursor, etc.

Alternatively you can connect to the hosted version with this config block, no installation required:

```
{
  "mcpServers": {
    "agentpmt": {
      "type": "streamable-http",
      "url": "https://api.agentpmt.com/mcp",
      "headers": {
        "Authorization": "Bearer <AGENTPMT_BEARER_TOKEN>",
        "x-instance-metadata": "{\"client\":\"generic-mcp\",\"platform\":\"remote\"}"
      }
    }
  }
}
```

[View MCP Connection Instructions](/docs/mcp-reference/connection) for more details.

#### How does an external agent use this tool?

- Page URL: https://www.agentpmt.com/faq
- Markdown URL: https://www.agentpmt.com/faq?format=agent-md

After the external agent is connected to an Agent Group that can use this tool, paste this prompt into the agent:

> Call the AgentPMT-Tool-Search-and-Execution tool with action 'get\_schema' and tool\_id 69618e485d4cf4d4b6af40f0 ("Gmail - All Email Actions"). Then call the same tool with action 'call\_tool', tool\_id 69618e485d4cf4d4b6af40f0, and the parameters needed for my request.

The agent should fetch the tool schema first, collect the required parameters for your request, and then call the tool through AgentPMT.

### Dependencies

This product has no public dependency products.