Universal Email Migration Toolkit

Migration Decision Tree

Use this matrix to determine the best migration path:

Source	Destination	Method	Complexity	Notes
Yahoo Mail	Gmail	IMAP → Gmail Import	Easy	Use app passwords
Yahoo Mail	Outlook	IMAP → Outlook Desktop	Medium	Manual folder setup
Zoho Mail	Gmail	IMAP → Gmail Import	Easy	Supports IMAP natively
Zoho Mail	Outlook	Microsoft Migration	Medium	Use Zoho IMAP settings
ProtonMail	Gmail	Export → Import	Hard	Limited export options
ProtonMail	Outlook	Manual forwarding	Hard	No bulk export
iCloud Mail	Gmail	IMAP → Gmail Import	Easy	Requires app password
iCloud Mail	Outlook	IMAP → Outlook	Medium	Limited folder support
Any IMAP	Any IMAP	IMAP bridging	Medium	Universal solution
Exchange On-prem	Cloud	PST export/import	Hard	Requires Exchange admin

Universal IMAP Migration Process

For most provider-to-provider migrations:

Step 1: Source Preparation

• Enable IMAP on source account (if not enabled by default)
• Create app password (Gmail, Yahoo, iCloud require this)
• Test connectivity using the IMAP test script
• Estimate data size using the mailbox size script
• Document folder structure for mapping reference

Step 2: Destination Setup

• Create target account with sufficient storage
• Enable IMAP access (for intermediary tools)
• Configure mail client (Outlook, Thunderbird, or web import)
• Set up folder structure matching source (if needed)
• Test inbound mail to verify account is working

Step 3: Migration Execution

Choose based on destination platform:

#### To Gmail (any source with IMAP)

• Gmail → Settings → Accounts → Import mail and contacts
• Enter source IMAP details from provider matrix
• Choose import options (last 30 days vs. all mail)
• Start import — Gmail handles the rest automatically

#### To Outlook/Microsoft 365

• Outlook Desktop → Add Account → IMAP source
• Set up both accounts in same Outlook profile
• Drag and drop folders from source to destination
• Alternative: Use Microsoft's import tools for bulk

#### IMAP-to-IMAP (Universal)

• Use desktop client (Outlook, Thunderbird, Apple Mail)
• Configure both accounts as IMAP
• Copy folders between accounts via client
• Monitor for errors and retry failed items

Step 4: Validation

• Compare email counts between source and destination
• Test key functionality (send, receive, search)
• Verify contacts and calendar if migrated
• Check folder structure matches expectations
• Validate largest messages and attachments

Email Backup and Export

Before any migration, create backups:

Source-Specific Export Methods

#### Gmail / Google Workspace

• Method: Google Takeout (takeout.google.com)
• Format: MBOX (Thunderbird compatible)
• Includes: Email, contacts, calendar
• Time: 2-48 hours depending on mailbox size

#### Outlook / Exchange

• Method: Export to PST file
• Format: PST (Outlook native)
• Process: File → Open & Export → Export to File
• Limitation: Desktop Outlook required

#### Yahoo Mail

• Method: IMAP download via email client
• Format: Various (depends on client)
• Process: Configure IMAP, sync all folders locally
• Note: No bulk export tool from Yahoo

#### Zoho Mail

• Method: IMAP export or Zoho's backup tool
• Format: MBOX or EML
• Process: Contact Zoho support for large mailboxes
• Alternative: IMAP sync to local client

#### iCloud Mail

• Method: IMAP download
• Format: Various (client dependent)
• Process: Configure IMAP with app password
• Limitation: No native export tool

#### ProtonMail

• Method: Individual email export only
• Format: EML files
• Process: Select emails individually, export
• Note: No bulk export due to encryption

See references/backup-export.md for detailed step-by-step procedures.

Common Migration Challenges

Challenge	Solution	Prevention
Authentication failures	Use app passwords, check 2FA settings	Test connectivity first
Size limitations	Split into batches, exclude large attachments	Check provider limits
Folder mapping issues	Document structure, plan manual creation	Map folders before migration
Missing emails	Check spam/junk, verify date ranges	Do incremental migration
Slow transfer speeds	Use multiple connections, off-peak hours	Plan adequate time
Character encoding	Ensure UTF-8 support in tools	Test with non-ASCII subjects

Provider-Specific Considerations

Yahoo Mail

• IMAP Limitations: Free accounts have folder limits
• Authentication: Must use app passwords with 2FA
• Best Practice: Migrate during off-peak hours (night/weekend)

Zoho Mail

• IMAP Support: Full IMAP access on all plans
• Bulk Migration: Zoho offers migration services for enterprise
• API Access: Available for custom migration tools

ProtonMail

• Major Limitation: No IMAP access due to encryption
• Workaround: Export to Thunderbird, then migrate from Thunderbird
• Enterprise: ProtonMail Bridge available for paid plans

iCloud Mail

• Storage Limits: 5GB free, consider upgrading temporarily
• IMAP Quirks: Some folders may not sync properly
• Performance: Slow IMAP response, plan extra time

On-Premises Exchange

• Admin Access: Required for PST export/import
• Network: Consider bandwidth limitations
• Legacy Versions: Older Exchange may need PST conversion

Troubleshooting Workflow

When migration fails or stalls:

• Check authentication — Re-enter passwords, regenerate app passwords
• Verify IMAP settings — Double-check server, port, SSL settings
• Test connectivity — Run scripts/imap-test.py with exact settings
• Check quotas — Verify destination has enough storage space
• Review logs — Look for specific error messages in client logs
• Retry smaller batches — Split large mailboxes into smaller chunks
• Contact support — Provider-specific issues may need support tickets

See references/troubleshooting.md for comprehensive error resolution guide.

Migration Best Practices

Planning Phase

• Inventory thoroughly — Document all email accounts, sizes, special requirements
• Test with pilot users — Never migrate entire organization without testing
• Communicate clearly — Set expectations with users about timeline and downtime
• Plan rollback — Always have a way to revert if migration fails

Execution Phase

• Monitor actively — Don't start migration and walk away
• Validate incrementally — Check each user/batch before proceeding
• Keep logs — Document what worked, what failed, and why
• Stay flexible — Be prepared to switch methods if primary approach fails

Post-Migration

• Validate data integrity — Compare counts, spot-check important emails
• Train users — New interface, different features, updated mobile setup
• Monitor performance — Watch for issues in first 48-72 hours
• Plan cleanup — When to disable old accounts, how long to retain access