email_migration/README.md

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

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

Requirements

• Python 3.6+ (pre-installed on Linux & macOS)
• IMAP access enabled on both email accounts
• Email account credentials (username/email and password)

Authentication Methods

The script supports flexible authentication with four possible configurations:

Option 1: Email-based Login (Most Common)

SOURCE_EMAIL=user@domain.de
SOURCE_USERNAME=

Used by: Gmail, Yahoo, Outlook, most modern providers

Option 2: Username + Email (Dual Method)

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

SOURCE_EMAIL=
SOURCE_USERNAME=mail_user123

Used by: Legacy systems, some cPanel hosting where email is unknown

Option 4: Email-only Login

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)

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

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

# 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

# Only migrate specific folders
INCLUDE_FOLDERS=INBOX,Sent,Important

# Skip unwanted folders  
EXCLUDE_FOLDERS=Trash,Spam,Junk

Performance Tuning

# 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

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

# .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)

# .env configuration  
INCLUDE_FOLDERS=INBOX
BATCH_SIZE=10
LOG_LEVEL=DEBUG

# Run migration
python3 email_migration.py

Example 3: Consolidate Multiple Accounts

# .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.