5.7 KiB
5.7 KiB
Email Organizer
A self-hosted email organization system that automates folder sorting and management through natural language configuration.
Core Value Proposition
- Natural Language Rules: Define email organization logic in plain English instead of writing complex filter rules
- Smart Separation: Automatically categorize emails into custom folders based on your rules
- IMAP Integration: Sync and manage folders directly from your email server
- User Authentication: Secure multi-user system with individual configurations
Technical Overview
Stack:
- Backend: Flask (Python 3.10+)
- Frontend: HTMX + AlpineJS + DaisyUI (Tailwind CSS)
- Database: PostgreSQL
- IMAP: Direct server integration
Key Components:
- Authentication System: User registration, login, and session management
- Folder Management: Create, edit, and organize email folders with natural language rules
- IMAP Service: Direct integration with email servers for folder synchronization
- User Interface: Modern, responsive UI with dynamic updates
Getting Started
Prerequisites
- Python 3.10+
- PostgreSQL 14+
- IMAP server access
Setup
# Install dependencies
pip install -r requirements.txt
# Set up development environment (PostgreSQL and IMAP server)
flask setup-dev
# Configure environment
cp .env.example .env
# (Edit .env with your DB/IMAP credentials)
# Initialize database
flask db upgrade
# Run development server
flask run
Features
Current Implementation
- User Authentication: Complete user registration and login system with password validation
- Folder Management: Create, edit, delete, and toggle email organization folders
- IMAP Integration: Configure and test connections to email servers
- Folder Synchronization: Import existing folders from IMAP servers
- Natural Language Rules: Define organization rules in plain English
- Priority System: Organize folders with priority levels
- Email Metrics: Track email counts and recent email information
User Interface
- Modern Design: Clean, responsive interface using DaisyUI
- Dynamic Updates: HTMX for seamless UI interactions without page reloads
- Modal System: Forms and configuration in intuitive modal dialogs
- Real-time Feedback: Immediate visual feedback for all operations
Architecture
The application follows a modular architecture with clear separation of concerns:
- Frontend Layer: HTMX + AlpineJS + DaisyUI for dynamic user interface
- Application Layer: Flask blueprints for modular feature organization
- Data Layer: PostgreSQL with SQLAlchemy ORM for data persistence
- Service Layer: IMAP service for email server communication
For detailed architecture information, see System Architecture.
Data Model
The system uses two main entities with a one-to-many relationship:
Users
| Column | Type | Description |
|---|---|---|
| id | Integer | Primary key |
| first_name | String | User's first name |
| last_name | String | User's last name |
| String | Unique identifier | |
| password_hash | String | Hashed password |
| imap_config | JSON | Server settings |
| created_at | DateTime | Account creation timestamp |
| updated_at | DateTime | Last update timestamp |
Folders
| Column | Type | Description |
|---|---|---|
| id | Integer | Primary key |
| user_id | Integer | Foreign key to user |
| name | String | Display name |
| rule_text | Text | Natural language rule |
| priority | Integer | Processing order (0=normal, 1=high) |
| organize_enabled | Boolean | Rule active status |
| total_count | Integer | Total emails in folder |
| pending_count | Integer | Emails to process |
| recent_emails | JSON | Recent email metadata |
| created_at | DateTime | Folder creation timestamp |
| updated_at | DateTime | Last update timestamp |
For detailed data model information, see Data Model.
Development Environment
The development environment includes:
- PostgreSQL Database: For data persistence
- Dovecot IMAP Server: For testing email integration
- Docker Compose: For easy service orchestration
Development Services
- Database: localhost:5432 (email_organizer_dev)
- IMAP Server: localhost:1143
- Test Users:
- user1@example.com / password1
- user2@example.com / password2
Roadmap
Current Status
- ✅ User authentication system
- ✅ Folder CRUD operations
- ✅ IMAP configuration and testing
- ✅ Folder synchronization from IMAP servers
- ✅ Natural language rule configuration
- ✅ Priority-based folder organization
- ✅ Email metrics tracking
Future Enhancements
- AI-Powered Rules: Advanced rule processing and recommendations
- Email Processing: Automated email classification and movement
- Advanced IMAP Features: Two-factor authentication, OAuth support
- Label Support: Integration with Gmail and other providers
- Admin Interface: Multi-user management and monitoring
- Hosted Service: Cloud-based offering
- Social Authentication: Google, Facebook, etc. login options
- Usage Analytics: Email processing statistics and insights
Contributing
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Note
: All new features require corresponding unit tests and documentation updates.