Skip to main content
GmailTool provides read-only access to Gmail for listing, searching, and fetching messages using the Gmail API.

​
Installation

Install the Google dependencies: 
pip install agentor[google]

​
Authentication

GmailTool requires Google OAuth2 credentials:
  1. Create credentials using the superauth library
  2. Save credentials to a JSON file
  3. Provide the path or set GOOGLE_USER_CREDENTIALS environment variable

​
Constructor

​
credentials_path
str
Path to saved user credentials JSON file. Defaults to GOOGLE_USER_CREDENTIALS env var or credentials.json
​
credentials
CredentialRecord
Pre-loaded credentials object. Overrides credentials_path if provided

​
Methods

​
search_messages

Search Gmail using the same query syntax as the web UI.
​
query
str
required
Gmail search query (e.g., from:alice has:attachment newer_than:7d)
​
label_ids
List[str]
Optional Gmail label IDs to filter by
​
after
str
ISO date string to filter messages after
​
before
str
ISO date string to filter messages before
​
limit
int
Number of messages to return (1-50, default: 20)

​
list_messages

List message IDs (fast, metadata-only).
​
label_ids
List[str]
Optional Gmail label IDs to filter by
​
q
str
Optional Gmail query string
​
limit
int
Number of messages to return (1-50, default: 20)
​
page_token
str
Pagination token from previous call
​
include_spam_trash
bool
Whether to include spam and trash (default: False)

​
get_message

Fetch a single Gmail message (metadata only).
​
message_id
str
required
Gmail message ID

​
get_message_body

Fetch a single Gmail message body for display or summarization.
​
message_id
str
required
Gmail message ID
​
prefer
str
“text” or “html” (default: “text”)
​
limit
int
Max characters to return (default: 50000)

​
Usage

​
Basic setup

from agentor import Agentor
from agentor.tools import GmailTool

gmail_tool = GmailTool(
    credentials_path="./credentials.json"
)

agent = Agentor(
    name="Email Assistant",
    model="gpt-4o-mini",
    tools=[gmail_tool]
)

result = agent.run("Search for unread emails from alice")
print(result)

​
Searching emails

from agentor.tools import GmailTool

gmail = GmailTool()

# Search for unread emails
result = gmail.search_messages("is:unread", limit=10)

# Search for emails with attachments
result = gmail.search_messages("has:attachment from:alice@example.com")

# Search by date range
result = gmail.search_messages(
    "newer_than:7d",
    after="2024-01-01",
    before="2024-12-31"
)

​
Reading message bodies

# Get message metadata
message_data = gmail.get_message("18c5f7a2b3d4e5f6")

# Get full message body
body = gmail.get_message_body(
    message_id="18c5f7a2b3d4e5f6",
    prefer="text",
    limit=10000
)

​
Privacy and security

GmailTool is read-only and cannot send emails, delete messages, or modify your Gmail account. It requires explicit OAuth consent from users.

​
Error handling

# Missing credentials
try:
    gmail = GmailTool(credentials_path="missing.json")
except FileNotFoundError as e:
    print(e)  # Credentials file not found

# Invalid message ID
result = gmail.get_message("invalid-id")
print(result)  # Error: ...

​
Source reference

src/agentor/tools/gmail.py:19
Last modified on March 4, 2026