Gmail API Endpoints
Relevant source files
The following files were used as context for generating this wiki page:
The Gmail API integration within OpenPoke serves as the bridge between the application's multi-agent system and the user's Google account. It utilizes Composio to facilitate OAuth authentication and provides a suite of endpoints for account management and email operations.
This system allows the Interaction Agent to request email tasks and the Execution Agent to perform actions such as searching, drafting, and sending emails. The integration is managed through a frontend Settings Modal and proxied via Next.js API routes to a FastAPI backend.
Sources: README.md:10-13, server/agents/interaction_agent/system_prompt.md:14-22
Authentication and Connection Management
OpenPoke manages Gmail connections through an OAuth flow initiated by the user. The system tracks connection states using a combination of user_id and connection_request_id.
Connection Flow
The connection process starts in the frontend SettingsModal.tsx, which calls the Next.js API route. This route proxies the request to the FastAPI backend service.
The backend initializes the connection using the initiate_connect function, which leverages the Composio client to generate a redirect URL.
Sources: server/services/gmail/client.py:169-201, web/app/api/gmail/connect/route.ts:4-31
Connection Status and Profile Retrieval
Once a connection is initiated, the system polls for status. The backend fetch_status function retrieves account details and caches the user's Gmail profile to minimize redundant API calls.
| Parameter | Type | Description |
|---|---|---|
user_id | string | The unique identifier for the user in the system. |
connection_request_id | string | The ID returned during the initiation phase. |
Sources: server/services/gmail/client.py:205-275, web/app/api/gmail/status/route.ts:4-34
Functional Endpoints
The Gmail module provides specialized tools for the Execution Agent to interact with the Gmail API. These are exposed through the execute_gmail_tool helper.
Core Email Operations
The system supports several high-level functions summarized in the following table:
| Tool Name | Backend Function | Description |
|---|---|---|
GMAIL_CREATE_EMAIL_DRAFT | gmail_create_draft | Creates an email draft with support for HTML and attachments. |
GMAIL_SEND_DRAFT | gmail_execute_draft | Sends a previously created draft. |
GMAIL_REPLY_TO_THREAD | gmail_reply_to_thread | Sends a reply within an existing thread. |
GMAIL_FORWARD_MESSAGE | gmail_forward_email | Forwards a message to a new recipient. |
GMAIL_FETCH_EMAILS | task_email_search | Agentic search using Gmail operators (e.g., from:, after:). |
Sources: server/agents/execution_agent/tools/gmail.py:22-150, server/agents/execution_agent/tasks/search_email/tool.py:146-175
Data Processing and Normalization
Emails retrieved from the API undergo cleaning via the EmailTextCleaner class. This process removes tracking pixels, truncates long URLs, and extracts readable text from HTML/multipart payloads.
# From server/services/gmail/processing.py:46-55
def clean_email_content(self, message: Dict[str, Any]) -> str:
"""Return cleaned plain-text representation of a Gmail message."""
html_content = self._extract_html_body(message)
text_content = self._extract_plain_body(message)
if html_content:
return self.clean_html_email(html_content)
if text_content:
return self.post_process_text(text_content)
return ""
Sources: server/services/gmail/processing.py:14-110
Disconnection Logic
Disconnection clears local caches and deactivates the connection on the Composio side. The backend identifies the connection to delete using either a connection_id or by listing all connections associated with a user_id.
The Gmail API endpoints ensure that the multi-agent system can securely and efficiently manage user communications while maintaining a clean, text-based representation of email data for LLM consumption.