email_migration/README.md

Email Migration Script

A Python script to migrate emails from one IMAP account to another with flexible folder organization options.

Features

• Flexible Import Options: Choose between organized folder structure or consolidated inbox
• 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

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
• App passwords (recommended for Gmail, Yahoo, Outlook)

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

Email Account Setup

# Source account (migrating FROM)
SOURCE_IMAP_SERVER=imap.gmail.com
SOURCE_EMAIL=old@gmail.com
SOURCE_PASSWORD=your_app_password

# Destination account (migrating TO)  
DEST_IMAP_SERVER=imap.gmail.com
DEST_EMAIL=new@gmail.com
DEST_PASSWORD=your_app_password

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

App Password Setup

Gmail: Google Account → Security → App Passwords
Yahoo: Account Security → Generate app password
Outlook: Account Security → App passwords

⚠️ Important: Use app passwords, not regular login passwords!

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: Full Gmail Migration with Organization

# .env configuration
SOURCE_EMAIL=old@gmail.com
DEST_EMAIL=new@gmail.com
IMPORT_FOLDER_NAME=OldAccount
EXCLUDE_FOLDERS=Trash,Spam

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

• Use app passwords instead of 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

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

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

Security Notes

• Never commit .env file to version control
• Use app passwords instead of account passwords
• Ensure SSL is enabled (*_IMAP_USE_SSL=True)
• Store credentials securely
• Test with non-critical accounts first

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

License

This script is provided as-is for educational and personal use. Test thoroughly before production use.