Gmail Service Overview

Relevant source files

The following files were used as context for generating this wiki page:

• server/services/gmail/client.py
• server/services/gmail/processing.py
• server/services/gmail/importance_watcher.py
• server/services/gmail/importance_classifier.py
• server/agents/execution_agent/tools/gmail.py
• server/agents/execution_agent/tasks/search_email/tool.py
• web/components/SettingsModal.tsx
• README.md

The Gmail Service is a core module of OpenPoke designed to facilitate email triage, proactive notification, and multi-agent interaction with a user's Gmail account. It leverages the Composio SDK for managed authentication and tool execution, allowing the system to perform complex tasks such as drafting, replying, forwarding, and agentic searching without direct handling of OAuth tokens by the application core.

The service consists of three primary layers: a communication layer for account management, a processing layer for email normalization and cleaning, and a proactive monitoring layer that identifies "important" emails using LLM-based classification.

Sources: README.md:9-11, server/services/gmail/client.py:46-70

Architecture and Connection Management

OpenPoke utilizes a singleton client architecture to manage connections to the Composio integration. User authentication is initiated through the web UI, which triggers an OAuth flow handled by Composio.

Connection Flow

The following diagram illustrates how a user connects their Gmail account and how the backend maintains the active connection state.

The diagram shows the lifecycle of a Gmail connection from the initial UI request to the final session state in the backend.
Sources: server/services/gmail/client.py:228-261, web/components/SettingsModal.tsx:162-205

Key Management Functions

Function	Description	Source
get_active_gmail_user_id	Retrieves the current active user ID from a thread-safe global lock.	client.py:38-41
initiate_connect	Starts the OAuth process and returns a redirect URL for user authorization.	client.py:228-251
fetch_status	Validates if the connection is ACTIVE or CONNECTED and populates the profile cache.	client.py:264-338
execute_gmail_tool	Proxy function that executes specific Gmail actions (e.g., GMAIL_CREATE_EMAIL_DRAFT) via Composio.	client.py:483-512

Email Processing and Normalization

Raw email data from the Gmail API (via Composio) is often cluttered with HTML, tracking pixels, and complex MIME structures. The EmailTextCleaner and ProcessedEmail dataclass provide a normalized interface for LLM consumption.

Email Cleaning Logic

1. HTML Extraction: Extracts text/html parts and uses BeautifulSoup to decompose style, script, and noise elements (e.g., footers, tracking pixels).
2. URL Truncation: Truncates long URLs and strips tracking parameters (utm_source, etc.) to save context window tokens.
3. Post-Processing: Unescapes HTML entities and reduces multiple newlines/whitespace into a concise format.

Sources: server/services/gmail/processing.py:21-70, server/services/gmail/processing.py:108-144

Data Structure: ProcessedEmail

@dataclass(frozen=True)
class ProcessedEmail:
    id: str
    thread_id: Optional[str]
    subject: str
    sender: str
    recipient: str
    timestamp: datetime
    clean_text: str
    has_attachments: bool
    attachment_count: int
    attachment_filenames: List[str]

Sources: server/services/gmail/processing.py:192-205

Agentic Search and Tooling

The system provides execution agents with specialized tools to interact with the user's inbox. The task_email_search tool is an orchestrator that performs multiple parallel queries to find the most relevant messages.

Search Orchestration Flow

This sequence shows the multi-step search process where the LLM refines search operators based on intermediate results.
Sources: server/agents/execution_agent/tasks/search_email/tool.py:112-167

Available Agent Tools

Tool Name	Purpose	Parameters
gmail_create_draft	Creates a new draft message.	recipient_email, subject, body, thread_id, is_html
gmail_execute_draft	Sends an existing draft.	draft_id
gmail_reply_to_thread	Sends a reply within a thread.	thread_id, recipient_email, message_body
gmail_forward_email	Forwards a specific message.	message_id, recipient_email, additional_text

Sources: server/agents/execution_agent/tools/gmail.py:21-140

Proactive Importance Monitoring

The ImportantEmailWatcher is a background service that proactively notifies the user of critical emails. It polls the inbox at set intervals and uses an LLM classifier to determine urgency.

Importance Classification Process

1. Poll: The watcher fetches emails from the last N minutes (default 10).
2. Filter: Skips emails already present in the GmailSeenStore.
3. Classify: Sends the metadata and cleaned body to the classify_email_importance service.
4. Notify: If the LLM marks the email as important, a summary is generated and dispatched to the InteractionAgentRuntime.

Sources: server/services/gmail/importance_watcher.py:73-108, server/services/gmail/importance_classifier.py:72-108

Classification Criteria

The importance_classifier.py uses a specific system prompt to guide the LLM:

"Only mark an email as important if it materially affects the user's plans, requires a prompt decision or action, is a security-sensitive OTP... Ignore order confirmations, routine marketing, newsletters."

Sources: server/services/gmail/importance_classifier.py:44-51

Conclusion

The Gmail Service integrates background monitoring with agent-driven tasks to create a proactive assistant experience. By separating raw API management (Composio) from high-level semantics (Importance Classifier and Search Orchestrator), the system allows agents to handle complex email workflows while ensuring the user is only notified of truly critical communications.

Sources: README.md:1-15, server/services/gmail/importance_watcher.py:170-178