karamelmar/email_migration
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add dual authentication support and comprehensive provider examples

Browse source 
Core functionality:
- Add dual authentication support (username + email fallback)
- Enhance IMAPConnection to try username first, then email
- Add SOURCE_USERNAME and DEST_USERNAME configuration options
- Improve authentication error handling and logging

Configuration updates:
- Add Host Europe to Securehost.de migration examples
- Include authentication method explanations for various providers
- Add comprehensive provider-specific settings (Host Europe, Securehost.de, etc.)
- Document username vs email login methods with examples

Documentation updates:
- Add dual authentication section in README
- Include Host Europe and Securehost.de specific examples
- Expand troubleshooting section with authentication help
- Add provider-specific troubleshooting guidance
- Include migration best practices

Features:
- Automatic fallback from username to email authentication
- Enhanced logging showing which authentication method succeeded
- Support for various hosting providers and their login requirements
- Improved error messages for authentication failures
This commit is contained in:
Elmar Sönser 2025-09-24 14:16:49 +02:00
commit 1d7fe31845
3 changed files with 211 additions and 53 deletions
Download patch file Download diff file Expand all files Collapse all files

144
README.md
View file

@ -1,15 +1,17 @@
# Email Migration Script
A Python script to migrate emails from one IMAP account to another with flexible folder organization options.
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
## Quick Start
@ -21,7 +23,27 @@ A Python script to migrate emails from one IMAP account to another with flexible
- Python 3.6+ (pre-installed on Linux & macOS)
- IMAP access enabled on both email accounts
- App passwords (recommended for Gmail, Yahoo, Outlook)
- Email account credentials (username/email and password)
## Authentication Methods
The script supports two authentication methods and automatically tries both:
### Method 1: Email-based Login (Most Common)
```env
SOURCE_EMAIL=user@domain.de
SOURCE_USERNAME=
```
**Used by**: Gmail, Yahoo, Outlook, most modern providers
### Method 2: Username-based Login
```env
SOURCE_EMAIL=user@domain.de
SOURCE_USERNAME=mail_user123
```
**Used by**: Some hosting providers, older email systems, cPanel hosting
The script automatically tries username first (if provided), then falls back to email authentication.
## Import Folder Options
@ -57,36 +79,57 @@ IMPORT_FOLDER_NAME=
## Configuration Guide
### Email Account Setup
### Host Europe to Securehost.de Migration Example
```env
# Source account (migrating FROM)
SOURCE_IMAP_SERVER=imap.gmail.com
SOURCE_EMAIL=old@gmail.com
SOURCE_PASSWORD=your_app_password
# 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 account (migrating TO)
DEST_IMAP_SERVER=imap.gmail.com
DEST_EMAIL=new@gmail.com
DEST_PASSWORD=your_app_password
# 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 |
|----------|-------------|------|-----|
| Gmail | `imap.gmail.com` | 993 | Yes |
| Outlook/Hotmail | `outlook.office365.com` | 993 | Yes |
| Yahoo | `imap.mail.yahoo.com` | 993 | Yes |
| Apple iCloud | `imap.mail.me.com` | 993 | Yes |
| 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) |
### App Password Setup
### Authentication Setup
**Gmail**: Google Account → Security → App Passwords
**Yahoo**: Account Security → Generate app password
**Outlook**: Account Security → App passwords
**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
⚠️ **Important**: Use app passwords, not regular login passwords!
**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
@ -123,13 +166,15 @@ LOG_LEVEL=ERROR # Errors only
## Usage Examples
### Example 1: Full Gmail Migration with Organization
### Example 1: Host Europe to Securehost.de with Organization
```bash
# .env configuration
SOURCE_EMAIL=old@gmail.com
DEST_EMAIL=new@gmail.com
IMPORT_FOLDER_NAME=OldAccount
EXCLUDE_FOLDERS=Trash,Spam
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
@ -169,6 +214,8 @@ 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'
@ -188,14 +235,23 @@ Errors encountered: 0
### Common Issues
**Authentication Failed**
- Use app passwords instead of regular passwords
- Check if username is required (try both with and without `SOURCE_USERNAME`)
- 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
- Check server settings and ports
**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 leaving `SOURCE_USERNAME` empty to use email login
- 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
@ -207,20 +263,39 @@ Errors encountered: 0
- 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 instead of account passwords
- 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
@ -234,6 +309,15 @@ email_migration/
└── 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.