Email Importance Classifier

Relevant source files

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

• server/services/gmail/importance_classifier.py
• server/services/gmail/importance_watcher.py
• server/services/gmail/processing.py
• server/services/gmail/seen_store.py
• server/agents/interaction_agent/system_prompt.md
• server/services/gmail/init.py

The Email Importance Classifier is a specialized LLM-powered service designed to evaluate incoming Gmail messages and determine if they warrant immediate proactive notification to the user. It functions as a critical component of the OpenPoke ecosystem, filtering through the noise of order confirmations, marketing, and newsletters to highlight high-priority items like security alerts (OTPs), meeting changes, and urgent decisions.

The system operates primarily through a background watcher that polls the user's inbox, processes email content to remove noise, and utilizes a structured tool-calling interface with OpenRouter-hosted models to perform the final classification. When an email is deemed important, the classifier generates a concise 2-3 sentence summary explaining why it requires attention, which is then dispatched to the interaction agent for user notification.

Architecture and Data Flow

The importance classification system is divided into three main layers: polling/orchestration, content normalization, and LLM-based decision logic.

Background Polling Orchestration

The ImportantEmailWatcher class manages the lifecycle of the classification process. It runs as a background task, polling Gmail at defined intervals (defaulting to 60 seconds) to find recent messages within a lookback window.

Content Normalization

Before classification, raw Gmail API responses are converted into ProcessedEmail objects. The EmailTextCleaner utility performs heavy lifting to ensure the LLM receives only relevant text, stripping HTML tags, style blocks, and tracking pixels while truncating long URLs.

Key processing steps include:

• HTML Stripping: Removing <style>, <script>, and <meta> tags.
• Noise Removal: Filtering out common email footer/header patterns and "View in browser" links.
• URL Truncation: Shortening long links to prevent token bloat while retaining essential information.
• Metadata Extraction: Capturing sender, recipient, timestamp, and attachment filenames.

Sources: server/services/gmail/processing.py:18-80, server/services/gmail/processing.py:215-255

LLM Classification Logic

The core logic resides in classify_email_importance, which uses a "system prompt" to define importance criteria and a "tool schema" to force structured output from the LLM.

Classification Criteria

The classifier is instructed to mark an email as important only if it:

• Materially affects the user's plans.
• Requires a prompt decision or action.
• Is a security-sensitive OTP or login notice.
• Contains high-priority updates (interviews, meeting changes).

Conversely, it is explicitly told to ignore routine marketing, generic receipts, and low-impact status notifications.
Sources: server/services/gmail/importance_classifier.py:53-61

Tool-Based Structured Output

The system utilizes a tool named mark_email_importance to receive structured data back from the LLM.

Field	Type	Description
important	boolean	True only if the email requires timely attention or coordination.
summary	string	A concise 2-3 sentence summary highlighting the sender, topic, and specific action required.

Sources: server/services/gmail/importance_classifier.py:23-45

Sequence of Classification

The following sequence diagram shows the interaction between the watcher, the classifier, and the external LLM provider.

Data Models and Storage

ProcessedEmail Schema

The system uses a standardized data structure to pass email information between services.

Field	Type	Description
id	str	The unique Gmail message ID.
subject	str	The email subject line.
sender	str	The sender's email address/name.
clean_text	str	The sanitized plain-text body of the email.
attachment_filenames	List[str]	A list of files attached to the email.
timestamp	datetime	Timezone-aware timestamp of when the email was received.

Sources: server/services/gmail/processing.py:186-200

Seen Store

To prevent duplicate notifications, the GmailSeenStore (referenced in the watcher) maintains a persistent list of processed message IDs in gmail_seen.json. This ensures that even if the server restarts, the system does not re-classify or re-notify the user about the same emails.
Sources: server/services/gmail/importance_watcher.py:40-45, server/services/gmail/seen_store.py

Configuration

The classifier relies on settings provided via the project's configuration management.

• API Key: Requires openrouter_api_key to communicate with the LLM.
• Model: Uses email_classifier_model (configured in settings) to perform the analysis.
• Poll Interval: Configurable via poll_interval_seconds (default 60.0).

Sources: server/services/gmail/importance_classifier.py:82-84, server/services/gmail/importance_watcher.py:34

Conclusion

The Email Importance Classifier acts as an intelligent gatekeeper for the user's inbox. By combining robust text cleaning with context-aware LLM analysis, it transforms a raw stream of emails into actionable notifications. This module is essential for the "proactive assistant" experience of OpenPoke, allowing the agent to interrupt the user only when truly significant events occur in their digital communications.