Skip to main content
The Gmail extension allows your agent to interact with your Gmail inbox — listing and searching messages, reading full email content, sending new emails, creating drafts, replying to threads, and trashing messages. It’s ideal for automating email workflows, monitoring important threads, or sending notifications directly from your agent.

​
Setup

If you haven’t set up Google OAuth yet, complete the Google OAuth Setup first.
1

Enable the Gmail API

In your Google Cloud project, navigate to APIs & Services → Library, search for Gmail API, and click Enable.
2

Install the Extension

ironclaw registry install gmail
3

Authorize Access

ironclaw tool auth gmail
IronClaw will provide a URL for you to authenticate - remember to follow the auth setup to enable your agent to capture the callback. If possible, it will open a browser window. Once approved, the token is stored securely and refreshed automatically.
If you already authenticated one Google service, you still need to authenticate each additional Google extension separately.

​
Available Actions

  • list_messages: List messages in your inbox with an optional Gmail search query, label filter, and result limit
  • get_message: Read the full content of a message by ID, including headers, body, and labels
  • send_message: Send a new email with recipient(s), subject, body, and optional CC addresses
  • create_draft: Save a message as a draft without sending it
  • reply_to_message: Reply to an existing message thread, keeping the conversation history intact
  • trash_message: Move a message to the trash

​
Example Usage

Once configured, you can ask your agent things like:
  • “What emails did I receive from alice@example.com this week?”
  • “Read my latest unread message”
  • “Send an email to bob@example.com with subject ‘Meeting Notes’ and a summary of today’s discussion”
  • “Draft a follow-up to the project proposal thread”
  • “Reply to the last message in the invoice thread saying the payment has been processed”
  • “Trash all emails from noreply@newsletter.com”

​
Gmail Search Syntax

The list_messages action accepts standard Gmail search queries in the query field:
QueryMatches
from:alice@example.comMessages from Alice
subject:invoiceMessages with “invoice” in the subject
is:unreadUnread messages
label:workMessages with the “work” label
after:2025/01/01Messages received after January 1, 2025
has:attachmentMessages with attachments
You can combine queries: from:alice@example.com is:unread lists all unread messages from Alice.