feat: Add duplicate detection, folder management, and enhanced UI

- Implement smart duplicate email detection using Message-ID and fallback signatures
- Add automatic folder creation with existing folder detection and reuse
- Enhance terminal output with colors, progress bars, and professional formatting
- Replace import folder functionality with original folder structure preservation
- Add comprehensive statistics tracking (duplicates, folder creation, etc.)
- Improve error handling with graceful date format fallbacks
- Add universal terminal compatibility with line-based formatting
- Update documentation and configuration files
- Provide clear user feedback for all migration decisions

Migration now intelligently skips duplicates, preserves folder structure,
and provides detailed feedback on what was migrated vs. what was skipped.

README.md

@@ -1,20 +1,170 @@
 # Email Migration Script
 
-A Python script to migrate emails from one IMAP account to another, preserving folder structure and metadata.
+A Python script to migrate emails from one IMAP account to another, preserving the original folder structure and metadata.
+
+## Features
+
+- **Preserves Original Folder Structure**: Emails are migrated to their exact original folders (INBOX → INBOX, Sent → Sent, etc.)
+- **Automatic Folder Creation**: Creates destination folders if they don't exist
+- **Flexible Authentication**: Supports both email and username login methods
+- **Folder Filtering**: Include/exclude specific folders from migration
+- **Batch Processing**: Handles large mailboxes efficiently
+- **Comprehensive Logging**: Detailed logs for troubleshooting
+- **Date Preservation**: Attempts to preserve original email dates (with fallback)
+- **Flag Preservation**: Maintains read/unread status
 
 ## Quick Start
 
-1. Edit .env file with your email credentials
-2. Run: python3 email_migration.py
+1. Copy `.env.template` to `.env`:
+   ```bash
+   cp .env.template .env
+   ```
+
+2. Edit `.env` file with your email credentials
+
+3. Run the migration:
+   ```bash
+   python3 email_migration.py
+   ```
 
 ## Requirements
+
 - Python 3.6+ (pre-installed on Linux & macOS)
 - No additional dependencies required
 
 ## Configuration
-Edit the .env file with your email account settings.
+
+All configuration is done through the `.env` file. Key settings include:
+
+### Required Settings
+- **Source Account**: `SOURCE_IMAP_SERVER`, `SOURCE_EMAIL`/`SOURCE_USERNAME`, `SOURCE_PASSWORD`
+- **Destination Account**: `DEST_IMAP_SERVER`, `DEST_EMAIL`/`DEST_USERNAME`, `DEST_PASSWORD`
+
+### Optional Settings
+- **Folder Filtering**: `INCLUDE_FOLDERS`, `EXCLUDE_FOLDERS`
+- **Migration Options**: `PRESERVE_FLAGS`, `PRESERVE_DATES`, `BATCH_SIZE`
+- **Logging**: `LOG_LEVEL`, `IMAP_TIMEOUT`
+
+## Folder Structure
+
+The script preserves the exact folder structure from the source account:
+
+```
+Source Server:          Destination Server:
+├── INBOX              →  ├── INBOX
+├── Sent               →  ├── Sent
+├── Drafts             →  ├── Drafts
+├── Archive            →  ├── Archive
+└── Custom Folder      →  └── Custom Folder
+```
+
+If a folder doesn't exist on the destination server, it will be created automatically.
+
+## Authentication
+
+The script supports multiple authentication methods:
+
+1. **Email + Password**: Most common for personal accounts
+2. **Username + Password**: Often used for business accounts
+3. **App Passwords**: Required for Gmail, Yahoo, and other providers with 2FA
+
+**Important**: Use app-specific passwords for accounts with two-factor authentication enabled.
+
+## Folder Filtering
+
+Control which folders to migrate:
+
+```bash
+# Migrate only specific folders
+INCLUDE_FOLDERS=INBOX,Sent,Drafts
+
+# Skip unwanted folders (default: skip trash and spam)
+EXCLUDE_FOLDERS=Trash,Spam,Junk
+```
+
+## Logging
+
+Check `email_migration.log` for detailed information:
+- Connection status
+- Migration progress
+- Error messages
+- Performance statistics
 
 ## Important Notes
-- Use app passwords, not regular passwords
-- Test with a small folder first
-- Check email_migration.log for detailed logs
+
+### Before Migration
+- **Test First**: Start with a small folder or test account
+- **App Passwords**: Use app-specific passwords, not regular passwords
+- **Backup**: Consider backing up important emails before migration
+
+### After Migration
+- **Webmail Clients**: Some webmail interfaces (like Roundcube) may not immediately show newly created folders
+- **Folder Visibility**: You may need to:
+  1. Refresh your webmail interface
+  2. Check folder settings/preferences
+  3. Manually subscribe to new folders if required
+
+### Performance Tips
+- Adjust `BATCH_SIZE` for optimal performance (default: 50)
+- Use `LOG_LEVEL=ERROR` for faster migration of large mailboxes
+- Increase `IMAP_TIMEOUT` for slow connections
+
+## Troubleshooting
+
+### Common Issues
+
+**Connection Failed**
+- Verify server settings and ports
+- Check if SSL is required
+- Ensure app passwords are used when needed
+
+**Authentication Failed**
+- Verify username/email and password
+- Check if two-factor authentication requires app password
+- Ensure IMAP access is enabled
+
+**Missing Folders After Migration**
+- Refresh webmail client
+- Check folder subscription settings
+- Look for folders in webmail preferences/settings
+
+**Slow Migration**
+- Reduce `BATCH_SIZE`
+- Increase `IMAP_TIMEOUT`
+- Check network connection stability
+
+### Getting Help
+
+1. Check the log file: `email_migration.log`
+2. Run with debug logging: `LOG_LEVEL=DEBUG`
+3. Test connection with a single folder first
+
+## Example Configuration
+
+```bash
+# Source account (Host Europe)
+SOURCE_IMAP_SERVER=mail.example.com
+SOURCE_IMAP_PORT=993
+SOURCE_EMAIL=user@example.com
+SOURCE_PASSWORD=your_app_password
+
+# Destination account (Gmail)
+DEST_IMAP_SERVER=imap.gmail.com
+DEST_IMAP_PORT=993
+DEST_EMAIL=user@gmail.com
+DEST_PASSWORD=your_gmail_app_password
+
+# Skip unwanted folders
+EXCLUDE_FOLDERS=Trash,Spam,Junk
+
+# Performance settings
+BATCH_SIZE=50
+LOG_LEVEL=INFO
+```
+
+## Security
+
+- Never commit `.env` files to version control
+- Use app-specific passwords when available
+- Delete temporary files after migration
+- Consider using encrypted connections only (`USE_SSL=True`)