{"id":30702978,"url":"https://github.com/haasonsaas/email-agent","last_synced_at":"2025-09-18T07:46:12.075Z","repository":{"id":307755750,"uuid":"1030123463","full_name":"haasonsaas/email-agent","owner":"haasonsaas","description":"AI-powered email management agent with TUI dashboard, CLI commands, and multi-agent categorization system. Supports Gmail integration, rule-based processing, and Docker deployment.","archived":false,"fork":false,"pushed_at":"2025-08-11T16:57:42.000Z","size":585,"stargazers_count":7,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-02T16:07:25.249Z","etag":null,"topics":["ai-agents","cli","crewai","docker","email-automation","email-management","gmail","python","textual","tui"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/haasonsaas.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-01T06:01:26.000Z","updated_at":"2025-08-31T07:20:59.000Z","dependencies_parsed_at":"2025-08-02T02:49:23.522Z","dependency_job_id":null,"html_url":"https://github.com/haasonsaas/email-agent","commit_stats":null,"previous_names":["haasonsaas/email-agent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/haasonsaas/email-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haasonsaas%2Femail-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haasonsaas%2Femail-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haasonsaas%2Femail-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haasonsaas%2Femail-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/haasonsaas","download_url":"https://codeload.github.com/haasonsaas/email-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haasonsaas%2Femail-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275731990,"owners_count":25518090,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-18T02:00:09.552Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","cli","crewai","docker","email-automation","email-management","gmail","python","textual","tui"],"created_at":"2025-09-02T16:02:10.673Z","updated_at":"2025-09-18T07:46:12.063Z","avatar_url":"https://github.com/haasonsaas.png","language":"Python","funding_links":[],"categories":["Agent Categories","Python"],"sub_categories":["\u003ca name=\"Unclassified\"\u003e\u003c/a\u003eUnclassified"],"readme":"# Email Agent 🤖📧\n\nA comprehensive CLI Email Agent with AI-powered multi-agent orchestration for intelligent email management, triage, and automation.\n\n## 🚀 Features\n\n### 🧠 AI-Powered Multi-Agent System\n- **Crew-AI Orchestration**: Multi-agent system with specialized roles\n- **Smart Categorization**: Automatic email categorization using ML\n- **Intelligent Prioritization**: AI-driven priority scoring and triage\n- **Action Extraction**: Extracts actionable items, commitments, and deadlines\n- **Thread Summarization**: AI-powered thread analysis with insights\n- **Learning System**: Learns from user feedback to improve decisions\n\n### 🏢 CEO Intelligence System\n- **Enhanced Labeling**: Advanced spam filtering with sender reputation scoring\n- **Relationship Intelligence**: Strategic contact profiling (board, investors, customers)\n- **Thread Continuity**: Conversation tracking with context-aware labeling\n- **Auto-Escalation**: VIP contact priority handling with smart routing\n- **Strategic Analysis**: Board member and investor communication prioritization\n\n### 📧 Email Connectors\n- **Gmail Integration**: Full Gmail API support with OAuth2\n- **IMAP Support**: Universal IMAP connector for any email provider\n- **Outlook Support**: Microsoft Graph API integration\n\n### 🏷️ Advanced Gmail SDK Features\n- **Smart Labels**: Automatic Gmail label creation and application\n- **Calendar Integration**: Auto-creates calendar events from meeting requests\n- **Smart Replies**: AI-generated reply suggestions\n- **Bulk Operations**: Efficient batch processing of emails\n\n### 📊 Intelligence \u0026 Analytics\n- **Daily Briefs**: AI-generated summaries with actionable insights\n- **Commitment Tracking**: Track commitments, deadlines, and follow-ups\n- **Thread Analysis**: Comprehensive thread summarization with business insights\n- **Performance Metrics**: Email processing statistics and effectiveness scores\n\n### 🖥️ Interface Options\n- **Rich CLI**: Feature-rich command-line interface with Typer\n- **Interactive TUI**: Beautiful terminal UI with Textual\n- **Docker Support**: Containerized deployment with persistence\n\n### 🔒 Privacy-First Design\n- **Local Storage**: SQLite database with no cloud dependencies\n- **Secure OAuth**: Industry-standard authentication flows\n- **Credential Protection**: Secure credential management\n\n## 📦 Installation\n\n### Prerequisites\n- Python 3.11+\n- Git\n- Docker (optional)\n\n### Quick Install\n```bash\ngit clone https://github.com/haasonsaas/email-agent.git\ncd email-agent\npip install -e .\n```\n\n### Docker Install\n```bash\ngit clone https://github.com/haasonsaas/email-agent.git\ncd email-agent\ndocker-compose up --build -d\n```\n\n## 🚀 Quick Start\n\n### 1. Initialize the Agent\n```bash\nemail-agent init\n```\n\n### 2. Add Gmail Connector\n```bash\nemail-agent config add-connector gmail\n```\n\n### 3. Sync Emails\n```bash\nemail-agent sync --since yesterday\n```\n\n### 4. View Daily Brief\n```bash\nemail-agent brief --today\n```\n\n### 5. Smart Action Processing\n```bash\nemail-agent smart-actions --apply-labels --replies\n```\n\n## 🛠️ Commands Overview\n\n### Core Operations\n```bash\n# Full sync with AI processing\nemail-agent sync --since \"1 week ago\" --brief\n\n# View system status and statistics\nemail-agent status\n\n# Generate daily brief\nemail-agent brief --today --detailed\n\n# Launch interactive dashboard\nemail-agent dashboard\n```\n\n### AI-Powered Features\n```bash\n# Extract actions from emails with Gmail integration\nemail-agent smart-actions --apply-labels --replies --events\n\n# Intelligent email handling\nemail-agent auto-handle --verbose\n\n# Summarize email threads\nemail-agent thread-summary --insights --overview\n\n# View smart inbox with AI triage\nemail-agent smart-inbox --limit 50\n```\n\n### 🏢 CEO Intelligence Commands\n```bash\n# Setup CEO label system in Gmail\nemail-agent ceo setup\n\n# Apply basic CEO labeling\nemail-agent ceo label --limit 200\n\n# Enhanced intelligence with relationship analysis\nemail-agent ceo intelligence --limit 100 --dry-run\n\n# Analyze strategic relationships\nemail-agent ceo relationships --limit 1000\n\n# Thread continuity analysis\nemail-agent ceo threads --limit 500\n\n# View CEO email insights\nemail-agent ceo analyze\n```\n\n### Commitment \u0026 Task Management\n```bash\n# View commitments and deadlines\nemail-agent commitments --report\n\n# View overdue items\nemail-agent commitments --overdue\n\n# Mark commitment as completed\nemail-agent mark-complete 123 --notes \"Completed successfully\"\n```\n\n### Learning \u0026 Feedback\n```bash\n# Provide feedback on AI decisions\nemail-agent feedback email-123 --feedback \"Category should be work\" --correct \"work\"\n\n# View learning statistics\nemail-agent learning-stats\n\n# Export learning data\nemail-agent export-learning learning-backup.json\n```\n\n### Configuration \u0026 Management\n```bash\n# Add email connectors\nemail-agent config add-connector gmail\nemail-agent config add-connector imap\n\n# Manage categorization rules\nemail-agent rule add \"sender:github.com\" work high\n\n# View categories and statistics\nemail-agent cat list\nemail-agent stats\n```\n\n## 🔧 Configuration\n\n### Environment Variables\n```bash\n# Required\nOPENAI_API_KEY=your-openai-key\nGOOGLE_CLIENT_ID=your-gmail-client-id\nGOOGLE_CLIENT_SECRET=your-gmail-client-secret\n\n# Optional\nDATABASE_URL=sqlite:///data/email_agent.db\nLOG_LEVEL=INFO\nBRIEF_OUTPUT_DIR=./briefs\n```\n\n### Gmail Setup\n1. Create a Google Cloud Project\n2. Enable Gmail API\n3. Create OAuth 2.0 credentials\n4. Add credentials to the agent configuration\n\n## 🏗️ Architecture\n\n### Multi-Agent System\n```\nEmailAgentCrew\n├── CollectorAgent      # Email synchronization\n├── CategorizerAgent    # AI-powered categorization\n├── SummarizerAgent     # Content summarization\n├── ActionExtractor     # Action item extraction\n├── ThreadSummarizer    # Thread analysis\n├── LearningSystem      # Feedback processing\n└── CommitmentTracker   # Task management\n```\n\n### Data Flow\n```\nEmail Sources → Collectors → Categorizers → Action Extractors → Database\n                    ↓              ↓              ↓\n              AI Processing → Smart Labels → Commitment Tracking\n                    ↓              ↓              ↓\n              Daily Briefs → Thread Summaries → Learning System\n```\n\n## 🎯 Use Cases\n\n### 📈 Executive/Manager\n- **Daily Brief**: Start each day with AI-generated email summaries\n- **Priority Inbox**: Focus on high-importance emails first\n- **Commitment Tracking**: Never miss deadlines or commitments\n- **Thread Summaries**: Quickly understand long email conversations\n\n### 👩‍💻 Developer/Knowledge Worker\n- **Smart Categorization**: Automatically organize technical emails\n- **Action Extraction**: Convert emails to actionable tasks\n- **Smart Labels**: Organize Gmail with intelligent labeling\n- **Learning System**: Improve AI decisions over time\n\n### 🏢 Teams \u0026 Organizations\n- **Bulk Processing**: Handle high email volumes efficiently\n- **Standardized Workflows**: Consistent email handling across team\n- **Analytics**: Understand email patterns and effectiveness\n- **Docker Deployment**: Easy containerized deployment\n\n## 📊 Example Outputs\n\n### Daily Brief\n```\n# Daily Email Brief - 2025-08-01\n\n## 📊 Statistics\n- Total Emails: 47\n- Unread: 23\n- High Priority: 8\n- Action Items: 12\n\n## 🔴 Urgent Actions\n1. Review budget proposal from Finance (Due: Today)\n2. Approve design mockups for client (Due: Tomorrow)\n3. Follow up on server migration status\n\n## 📅 Meetings \u0026 Events  \n- Team standup moved to 2 PM\n- Client presentation scheduled for Friday\n\n## 💡 Key Insights\n- 40% increase in support emails this week\n- 3 potential sales opportunities identified\n- Security alert requires immediate attention\n```\n\n### Smart Actions Output\n```\n🔍 Smart Action Extraction Starting...\nFound 15 emails to analyze for actions\n\n📧 Budget Q4 Planning Meeting Request\n   From: finance@company.com\n   📢 Needs response: urgent\n   📋 Actions: 1\n     • Review Q4 budget spreadsheet (Due: 2025-08-05)\n   📅 Meetings: 1\n     • schedule meeting\n   🏷️  Gmail labels applied\n   💬 Smart reply generated (234 chars)\n\n📊 Action Extraction Summary:\n  📋 Total action items: 23\n  🤝 Total commitments: 7\n  📅 Meeting requests: 4\n  ⏰ Items with deadlines: 15\n\n⚠️  3 items due TODAY!\n📅 8 items due this week\n```\n\n## 🧪 Development\n\n### Setup Development Environment\n```bash\ngit clone https://github.com/haasonsaas/email-agent.git\ncd email-agent\npip install -e \".[dev]\"\n```\n\n### Running Tests\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=email_agent\n\n# Type checking\nmypy src/email_agent\n```\n\n### Code Quality\n```bash\n# Format code\nblack src/\nisort src/\n\n# Lint code  \nruff check src/\n\n# Quality analysis\npyrefly check\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- **OpenAI** for GPT-4 integration\n- **Google** for Gmail API\n- **Crew-AI** for multi-agent orchestration\n- **Typer** and **Textual** for beautiful CLI/TUI interfaces\n- **Rich** for terminal formatting\n- **SQLAlchemy** for robust data management\n\n## 🚀 Roadmap\n\n- [ ] Microsoft Outlook/Exchange integration\n- [ ] Slack/Teams integration for notifications\n- [ ] Natural language query interface\n- [ ] Email template generation\n- [ ] Advanced analytics dashboard\n- [ ] Multi-user support\n- [ ] Mobile app companion\n- [ ] Integration with task management tools (Todoist, Notion, etc.)\n\n---\n\n**Built for productivity. Powered by AI. Privacy-first.** 🚀","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaasonsaas%2Femail-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhaasonsaas%2Femail-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaasonsaas%2Femail-agent/lists"}