How wayswe/auto-gmail-responder works
Project Type and Purpose
• This is a lightweight, local Windows-only automation tool written in Python (packaged as both a .py script and a standalone .exe).
• It watches a Gmail inbox, applies user-defined filters/prompts (from prompt_settings.csv), uses the OpenAI API to generate replies, sends those replies back through Gmail, and finally moves responded emails to a dedicated label.
• Per your “Please add SMS set up” instruction, we’ll also show how to integrate an SMS notification service (e.g., Twilio) so that, upon sending an email reply, the system can push an SMS alert to a user or administrator.
File Structure Analysis
• Top level:
• auto_gmail_responder.py (core script)
• auto_gmail_responder.exe (Windows build of the script)
• settings.env (configuration file for API keys, Gmail creds, run parameters)
• prompt_settings.csv (defines filters and ChatGPT prompts)
• README.md, LICENSE
• No “frontend/backend” split—this is a single process running locally.
• Uses environment variables (.env) for secrets.
• Relies on external REST APIs (Gmail, OpenAI, and now SMS).
Key Architecture Insights from README
• Single long-running service: polls Gmail at intervals set via settings.env.
• Filter engine: loads CSV rules, applies them to incoming messages.
• OpenAI integration: sends prompt + email content, receives AI-generated response.
• Gmail send + move: uses Gmail SMTP/IMAP or Gmail API to reply and relabel.
• Runs locally—no cloud deployment layer.
Main Components
a. Internal Components (deployed on the User’s Windows PC)
• Scheduler/Watcher Service (auto_gmail_responder.exe)
• Filter & Prompt Loader (reads prompt_settings.csv)
• OpenAI Client Module
• Gmail Client Module (IMAP/SMTP or Gmail API wrapper)
• SMS Notification Module (e.g., Twilio Python client)
• Configuration Store (settings.env)
b. External Services
• Gmail API Endpoint
• OpenAI API Endpoint
• SMS Provider API Endpoint (e.g., Twilio)
c. Optional Data Stores
• Local Log Files (for diagnostics)
Relationships and Data Flows
1. Scheduler triggers “CheckInbox” every N seconds.
2. Gmail Client polls Gmail API → retrieves new messages.
3. Filter Module evaluates each message against prompt_settings.csv.
4. For matching messages:
a. Prompt Builder injects email content into the user’s ChatGPT prompt.
b. OpenAI Client calls the OpenAI API → returns AI-generated text.
c. Gmail Client sends reply via SMTP/Gmail API.
d. Gmail Client moves original message to “gpt-auto-replied” label.
e. SMS Notification Module (new) sends an SMS alert (via Twilio REST API) to a configured phone number, including metadata (sender, subject, timestamp).
5. Loop back to scheduler.
Architectural Patterns and Principles
• Single-process event loop/polling model.
• Separation of concerns: polling, filtering, AI processing, email operations, SMS notifications.
• Configuration-driven: behaviors controlled by .env and CSV, minimizing code changes.
• Fail-safe design: local execution, no persistent data; clear exit eliminates data retention.
Technologies and Libraries
• Python 3.x / PyInstaller (for .exe)
• python-dotenv (for .env parsing)
• pandas or csv module (for prompt_settings.csv)
• google-api-python-client or imaplib/smtplib (for Gmail)
• openai Python SDK
• twilio Python SDK (for SMS)
Final Recommendations
• SMS Notification Module and show how it receives a trigger after email reply.
• Polling intervals and rule evaluation order as annotations if desired.
• Keep the overall flow clear: Inbox → Filter → AI → Reply → Move & SMS.