diff --git a/.env.template b/.env.template index 94d8a7a..c2cda1a 100644 --- a/.env.template +++ b/.env.template @@ -126,79 +126,3 @@ LOG_LEVEL=INFO # TEMP_DOWNLOAD_DIR: Temporary files directory # ./temp_emails (default) | /tmp/emails | C:\Temp\emails TEMP_DOWNLOAD_DIR=./temp_emails - -# ============================================================================ -# AUTHENTICATION EXAMPLES -# ============================================================================ - -# Option 1: Email-based login (most common): -# SOURCE_EMAIL=user@domain.de -# SOURCE_USERNAME= -# → Script tries: user@domain.de - -# Option 2: Username-based login: -# SOURCE_EMAIL=user@domain.de -# SOURCE_USERNAME=mail_user123 -# → Script tries: mail_user123, fallback to user@domain.de - -# Option 3: Username-only (email optional): -# SOURCE_EMAIL= -# SOURCE_USERNAME=mail_user123 -# → Script tries: mail_user123 only - -# Option 4: Email-only (username optional): -# SOURCE_EMAIL=user@domain.de -# SOURCE_USERNAME= -# → Script tries: user@domain.de only - -# Host Europe specific: -# SOURCE_USERNAME=email_account_name (from Host Europe KIS) -# SOURCE_USERNAME= (if using Easy-Mail-Login) - -# ============================================================================ -# PROVIDER-SPECIFIC EXAMPLES -# ============================================================================ - -# Host Europe to Securehost.de Migration: -# SOURCE_IMAP_SERVER=wp123456.mail.server-he.de -# SOURCE_EMAIL=user@olddomain.de -# SOURCE_USERNAME=mail_account_he -# DEST_IMAP_SERVER=mail.securehost.de -# DEST_EMAIL=user@securehost.de -# DEST_USERNAME= - -# Host Europe Settings: -# Server format: wpxxxxxxxx.mail.server-he.de (get from KIS) -# Port: 993 (SSL) or 143 (TLS) -# Username: Check KIS for account name or use email if Easy-Mail-Login enabled - -# Securehost.de Settings: -# Server: mail.securehost.de (typical format) -# Port: 993 (SSL recommended) -# Authentication: Usually email-based, check with provider - -# Other German Providers: -# Strato: imap.strato.de:993 (email login) -# 1und1/IONOS: imap.1und1.de:993 (username: username@domain) -# All-Inkl: mail.all-inkl.com:993 (username varies) -# Hetzner: mail.your-server.de:993 (email login) - -# Gmail (if needed): -# imap.gmail.com:993 (requires app password, email login) - -# ============================================================================ -# MIGRATION EXAMPLES -# ============================================================================ - -# Example 1: Host Europe to Securehost.de with organization -# IMPORT_FOLDER_NAME=HostEurope_Migration -# Result: Clean separation in destination - -# Example 2: Consolidate everything to main inbox -# IMPORT_FOLDER_NAME= -# Result: All emails in main INBOX - -# Example 3: Test migration with one folder -# INCLUDE_FOLDERS=INBOX -# BATCH_SIZE=10 -# LOG_LEVEL=DEBUG diff --git a/README.md b/README.md index da4bb6e..8ef63c9 100644 --- a/README.md +++ b/README.md @@ -1,343 +1,20 @@ # Email Migration Script -A Python script to migrate emails from one IMAP account to another with flexible folder organization and dual authentication support. - -## Features - -- **Flexible Import Options**: Choose between organized folder structure or consolidated inbox -- **Dual Authentication**: Supports both username and email-based login methods -- **Folder Filtering**: Include/exclude specific folders from migration -- **Metadata Preservation**: Maintain email flags, dates, and other metadata -- **Batch Processing**: Configurable batch sizes for optimal performance -- **Comprehensive Logging**: Detailed logs for monitoring and troubleshooting -- **SSL Security**: Secure connections with SSL/TLS support -- **Provider Compatibility**: Works with various email providers and hosting services +A Python script to migrate emails from one IMAP account to another, preserving folder structure and metadata. ## Quick Start -1. **Install**: No dependencies required - uses Python standard library -2. **Configure**: Copy `.env.template` to `.env` and add your email credentials -3. **Run**: `python3 email_migration.py` +1. Edit .env file with your email credentials +2. Run: python3 email_migration.py ## Requirements - - Python 3.6+ (pre-installed on Linux & macOS) -- IMAP access enabled on both email accounts -- Email account credentials (username/email and password) +- No additional dependencies required -## Authentication Methods +## Configuration +Edit the .env file with your email account settings. -The script supports flexible authentication with four possible configurations: - -### Option 1: Email-based Login (Most Common) -```env -SOURCE_EMAIL=user@domain.de -SOURCE_USERNAME= -``` -**Used by**: Gmail, Yahoo, Outlook, most modern providers - -### Option 2: Username + Email (Dual Method) -```env -SOURCE_EMAIL=user@domain.de -SOURCE_USERNAME=mail_user123 -``` -**Used by**: Some hosting providers - tries username first, falls back to email - -### Option 3: Username-only Login -```env -SOURCE_EMAIL= -SOURCE_USERNAME=mail_user123 -``` -**Used by**: Legacy systems, some cPanel hosting where email is unknown - -### Option 4: Email-only Login -```env -SOURCE_EMAIL=user@domain.de -SOURCE_USERNAME= -``` -**Used by**: When you're certain email authentication is the only method - -**Requirements**: You must provide either SOURCE_EMAIL or SOURCE_USERNAME (or both). Same applies to destination settings. - -## Import Folder Options - -### Option 1: Organized Import (Recommended) - -```env -IMPORT_FOLDER_NAME=Imported -``` - -**Result**: All source folders become subfolders within "Imported" -- Source `INBOX` → Destination `Imported/INBOX` -- Source `Sent` → Destination `Imported/Sent` -- Source `Drafts` → Destination `Imported/Drafts` - -**Benefits**: -- Preserves original folder structure -- Keeps imported emails separate from existing emails -- Easy to locate and organize imported content - -### Option 2: Consolidated Import - -```env -IMPORT_FOLDER_NAME= -``` - -**Result**: All emails go directly to destination INBOX -- All source folders → Destination `INBOX` - -**Benefits**: -- Simple single-folder result -- Useful for merging multiple accounts -- Good for basic email consolidation - -## Configuration Guide - -### Host Europe to Securehost.de Migration Example - -```env -# Source: Host Europe -SOURCE_IMAP_SERVER=wp123456.mail.server-he.de -SOURCE_IMAP_PORT=993 -SOURCE_EMAIL=user@olddomain.de -SOURCE_USERNAME=mail_account_name -SOURCE_PASSWORD=your_hosteurope_password -SOURCE_IMAP_USE_SSL=True - -# Destination: Securehost.de -DEST_IMAP_SERVER=mail.securehost.de -DEST_IMAP_PORT=993 -DEST_EMAIL=user@securehost.de -DEST_USERNAME= -DEST_PASSWORD=your_securehost_password -DEST_IMAP_USE_SSL=True - -# Import with organization -IMPORT_FOLDER_NAME=HostEurope_Migration -``` - -### Common IMAP Servers - -| Provider | IMAP Server | Port | SSL | Authentication | -|----------|-------------|------|-----|----------------| -| Host Europe | `wpXXXXXX.mail.server-he.de` | 993 | Yes | Username or Email | -| Securehost.de | `mail.securehost.de` | 993 | Yes | Email (typical) | -| Gmail | `imap.gmail.com` | 993 | Yes | Email + App Password | -| Outlook/Hotmail | `outlook.office365.com` | 993 | Yes | Email + App Password | -| Strato | `imap.strato.de` | 993 | Yes | Email | -| 1und1/IONOS | `imap.1und1.de` | 993 | Yes | Username@domain | -| All-Inkl | `mail.all-inkl.com` | 993 | Yes | Username (varies) | - -### Authentication Setup - -**Host Europe**: -1. Get server name from Host Europe KIS: `wpXXXXXX.mail.server-he.de` -2. Use email account name as username OR enable Easy-Mail-Login to use email -3. Check KIS for exact authentication method - -**Securehost.de**: -1. Server typically: `mail.securehost.de` or `mail.yourdomain.de` -2. Usually uses email-based authentication -3. Contact support if unsure about authentication method - -**Gmail/Yahoo/Outlook**: -1. Must use app passwords (not regular passwords) -2. Enable IMAP access in account settings -3. Use email address for authentication - -## Advanced Configuration - -### Folder Filtering - -```env -# Only migrate specific folders -INCLUDE_FOLDERS=INBOX,Sent,Important - -# Skip unwanted folders -EXCLUDE_FOLDERS=Trash,Spam,Junk -``` - -### Performance Tuning - -```env -# Batch size (emails per batch) -BATCH_SIZE=50 # Default balance -BATCH_SIZE=10 # Conservative (slow connections) -BATCH_SIZE=100 # Aggressive (fast connections) - -# Connection timeout -IMAP_TIMEOUT=60 # Default -IMAP_TIMEOUT=120 # Slow connections -``` - -### Logging and Debugging - -```env -LOG_LEVEL=INFO # Normal operation -LOG_LEVEL=DEBUG # Detailed troubleshooting -LOG_LEVEL=ERROR # Errors only -``` - -## Usage Examples - -### Example 1: Host Europe to Securehost.de with Organization -```bash -# .env configuration -SOURCE_IMAP_SERVER=wp987654.mail.server-he.de -SOURCE_EMAIL=old@company.de -SOURCE_USERNAME=company_mail -DEST_IMAP_SERVER=mail.securehost.de -DEST_EMAIL=new@company.de -IMPORT_FOLDER_NAME=HostEurope_Backup - -# Run migration -python3 email_migration.py -``` - -### Example 2: Test Migration (INBOX only) -```bash -# .env configuration -INCLUDE_FOLDERS=INBOX -BATCH_SIZE=10 -LOG_LEVEL=DEBUG - -# Run migration -python3 email_migration.py -``` - -### Example 3: Consolidate Multiple Accounts -```bash -# .env configuration -IMPORT_FOLDER_NAME= -# This puts all emails in main INBOX - -# Run migration -python3 email_migration.py -``` - -## Monitoring Progress - -The script provides detailed logging in multiple places: - -1. **Console Output**: Real-time progress updates -2. **Log File**: `email_migration.log` with detailed information -3. **Final Summary**: Complete migration statistics - -Example output: -``` -Email Migration Script -================================================== -[INFO] Import folder configuration: All emails will be imported to subfolders within "Imported" -[INFO] Connected to wp123456.mail.server-he.de using username: mail_account -[INFO] Connected to mail.securehost.de using email: user@securehost.de -[INFO] Found 5 folders to process -[INFO] Processing folder: INBOX -[INFO] Migrating 'INBOX' -> 'Imported/INBOX' -[INFO] Downloaded 150/150 messages from INBOX -[INFO] Uploaded 150/150 messages to Imported/INBOX -[INFO] Folder 'INBOX' -> 'Imported/INBOX' completed: 150 downloaded, 150 uploaded - -Migration completed! -Folders processed: 5 -Total emails downloaded: 1250 -Total emails uploaded: 1250 -Errors encountered: 0 -``` - -## Troubleshooting - -### Common Issues - -**Authentication Failed** -- Try different authentication combinations: - - Email only: Set `SOURCE_USERNAME=` (empty) - - Username only: Set `SOURCE_EMAIL=` (empty) - - Both: Provide both values for fallback -- Verify server address from your hosting provider -- For Host Europe: Get exact server name from KIS panel -- For Gmail/Yahoo: Use app passwords, not regular passwords -- Enable IMAP access in email account settings - -**Connection Timeout** -- Increase `IMAP_TIMEOUT` value -- Reduce `BATCH_SIZE` for stability -- Check network connection -- Verify server address and port - -**Username vs Email Login Issues** -- Try all combinations: - 1. Email only: `SOURCE_EMAIL=user@domain.de`, `SOURCE_USERNAME=` - 2. Username only: `SOURCE_EMAIL=`, `SOURCE_USERNAME=username123` - 3. Both (fallback): Provide both values -- For Host Europe: Check if Easy-Mail-Login is enabled -- Contact your hosting provider for authentication method -- Check provider documentation for login format - -**Folder Creation Failed** -- Verify destination account has folder creation permissions -- Check for special characters in folder names -- Some providers have folder name restrictions - -**Partial Migration** -- Check logs in `email_migration.log` -- Re-run script - it will skip already migrated emails -- Use `INCLUDE_FOLDERS` to retry specific folders - -### Provider-Specific Troubleshooting - -**Host Europe**: -- Server format: `wpXXXXXX.mail.server-he.de` (get exact name from KIS) -- Username: Use email account name from KIS or enable Easy-Mail-Login -- SSL: Port 993 recommended, port 143 with TLS also supported - -**Securehost.de**: -- Server typically: `mail.securehost.de` or `mail.yourdomain.de` -- Authentication: Usually email-based, contact support if unsure -- SSL: Port 993 standard - -**Gmail/Outlook**: -- Must generate app passwords from account security settings -- Regular passwords won't work due to security restrictions -- Enable IMAP in account settings first - -### Getting Help - -1. **Enable Debug Logging**: Set `LOG_LEVEL=DEBUG` -2. **Check Log File**: Review `email_migration.log` -3. **Test Small First**: Use `INCLUDE_FOLDERS=INBOX` and `BATCH_SIZE=10` -4. **Verify Credentials**: Test account access with email client first -5. **Try Both Auth Methods**: Test with and without username - -## Security Notes - -- Never commit `.env` file to version control -- Use app passwords for Gmail, Yahoo, Outlook instead of account passwords -- Ensure SSL is enabled (`*_IMAP_USE_SSL=True`) -- Store credentials securely -- Test with non-critical accounts first -- Enable two-factor authentication where supported - -## File Structure - -``` -email_migration/ -├── email_migration.py # Main script -├── .env.template # Configuration template -├── .env # Your configuration (create from template) -├── email_migration.log # Generated log file -├── temp_emails/ # Temporary files (auto-created) -└── README.md # This file -``` - -## Migration Best Practices - -1. **Test First**: Always test with a small subset of emails first -2. **Backup**: Ensure you have backups of important emails -3. **Network**: Use stable internet connection for large migrations -4. **Authentication**: Verify login credentials work before starting -5. **Monitoring**: Watch logs during migration for any issues -6. **Cleanup**: Clean up temporary files after successful migration - -## License - -This script is provided as-is for educational and personal use. Test thoroughly before production use. \ No newline at end of file +## Important Notes +- Use app passwords, not regular passwords +- Test with a small folder first +- Check email_migration.log for detailed logs