swarmauri_tool_gmail 0.11.0.dev1

example community package

Swarmauri Tool Gmail

Tools for sending and reading Gmail messages via Google Workspace service-account delegation. Provides GmailSendTool and GmailReadTool wrappers around the Gmail REST API.

Features

• GmailSendTool sends HTML emails to one or more recipients.
• GmailReadTool fetches messages matching a Gmail search query and formats key headers.
• Both tools authenticate with googleapiclient using a service account JSON file and delegated user email.

Prerequisites

• Python 3.10 or newer.
• Google Cloud service account with Gmail API enabled and domain-wide delegation to the target user.
• Credentials JSON file with the https://www.googleapis.com/auth/gmail.send and/or https://www.googleapis.com/auth/gmail.readonly scopes.
• Install google-api-python-client and google-auth (pulled in automatically).

Installation

# pip
pip install swarmauri_tool_gmail

# poetry
poetry add swarmauri_tool_gmail

# uv (pyproject-based projects)
uv add swarmauri_tool_gmail

Sending Email

from swarmauri_tool_gmail import GmailSendTool

send_tool = GmailSendTool(
    credentials_path="service-account.json",
    sender_email="[e-mail]",
)

result = send_tool(
    recipients="[e-mail]",
    subject="Test Email",
    htmlMsg="<p>Hello, this is a test email!
</p>",
)

print(result)

Reading Email

from swarmauri_tool_gmail import GmailReadTool

read_tool = GmailReadTool(
    credentials_path="service-account.json",
    sender_email="[e-mail]",
)

result = read_tool(query="is:unread", max_results=5)
print(result["gmail_messages"])

Tips

• Ensure the service account has been granted domain-wide delegation and that the Gmail API is enabled in Google Cloud console.
• Store credentials securely (Secrets Manager, Vault) and inject the file path via environment variables.
• When sending to multiple recipients, supply a comma-separated string (Gmail handles the formatting).
• For message bodies beyond simple HTML, extend the tool to add attachments or alternative MIME parts.

Want to help?

If you want to contribute to swarmauri-sdk, read up on our guidelines for contributing that will help you get started.