6ef7979445
- Implement smart duplicate email detection using Message-ID and fallback signatures - Add automatic folder creation with existing folder detection and reuse - Enhance terminal output with colors, progress bars, and professional formatting - Replace import folder functionality with original folder structure preservation - Add comprehensive statistics tracking (duplicates, folder creation, etc.) - Improve error handling with graceful date format fallbacks - Add universal terminal compatibility with line-based formatting - Update documentation and configuration files - Provide clear user feedback for all migration decisions Migration now intelligently skips duplicates, preserves folder structure, and provides detailed feedback on what was migrated vs. what was skipped.
170 lines
No EOL
4.9 KiB
Markdown
170 lines
No EOL
4.9 KiB
Markdown
# 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`:
|
|
```bash
|
|
cp .env.template .env
|
|
```
|
|
|
|
2. Edit `.env` file with your email credentials
|
|
|
|
3. Run the migration:
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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`) |