email_migration/README.md

Email Migration Script

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. Copy .env.template to .env:

   cp .env.template .env
   

2. Edit .env file with your email credentials

3. Run the migration:

   python3 email_migration.py
   

Requirements

• Python 3.6+ (pre-installed on Linux & macOS)
• No additional dependencies required

Configuration

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:

# 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

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

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