Email Migration Dashboard

A production-ready Python tool for migrating emails between IMAP accounts with a beautiful Rich TUI dashboard and Discord webhook notifications.

Features

• 🔄 Multi-Account Migration: Migrate emails from multiple source accounts to destination accounts
• 📊 Live Dashboard: Real-time Rich TUI showing progress, statistics, and errors
• 🔔 Discord Notifications: Get notified on start, completion, errors, and periodic updates
• ⚙️ Flexible Configuration: Interactive wizard or YAML/JSON config files
• 🚀 Fully Async: High-performance async/await implementation
• 🛡️ Production Ready: Error handling, logging, graceful shutdown

Requirements

• Python 3.12+
• uv package manager

Installation

Install uv

If you don't have uv installed:

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Linux/Mac
curl -LsSf https://astral.sh/uv/install.sh | sh

Install Dependencies

uv pip install -e .

Or using uv directly:

uv sync

Quick Start

1. Interactive Setup

Run the interactive configuration wizard:

uv run cli.py interactive

This will guide you through:

• Setting up source and destination IMAP accounts
• Configuring folders to migrate
• Setting up Discord webhook (optional)

The wizard will save your configuration to a YAML file.

2. Run Migration

Once you have a config file:

uv run cli.py run --config config.yaml

3. Validate Configuration

Check if your configuration is valid:

uv run cli.py check --config config.yaml

Configuration

YAML Configuration

Create a config.yaml file (see config.example.yaml for template):

accounts:
  - name: "my-email"
    source:
      host: "imap.example.com"
      port: 993
      username: "user@example.com"
      password: "password"
      use_ssl: true
    destination:
      host: "imap.destination.com"
      port: 993
      username: "user@destination.com"
      password: "password"
      use_ssl: true
    folders: []  # Empty = all folders
    skip_folders: ["Trash", "Spam"]

discord:
  webhook_url: "https://discord.com/api/webhooks/..."
  notify_on_start: true
  notify_on_complete: true
  notify_on_error: true
  periodic_updates: false
  update_interval_minutes: 30

Configuration Options

IMAP Settings

• host: IMAP server hostname
• port: IMAP port (usually 993 for SSL, 143 for non-SSL)
• username: IMAP username/email
• password: IMAP password
• use_ssl: Use SSL/TLS (default: true)
• verify_ssl: Verify SSL certificates (default: true)

Account Settings

• name: Unique name for this account migration
• folders: List of folders to migrate (empty = all folders)
• skip_folders: List of folders to skip

Discord Settings

• webhook_url: Discord webhook URL (optional)
• notify_on_start: Send notification when migration starts
• notify_on_complete: Send notification when migration completes
• notify_on_error: Send notification on errors
• periodic_updates: Send periodic progress updates
• update_interval_minutes: Minutes between periodic updates

Usage

CLI Commands

# Interactive configuration wizard
uv run cli.py interactive

# Run migration from config file
uv run cli.py run --config config.yaml

# Validate configuration
uv run cli.py check --config config.yaml

Unattended Mode

For server deployments, use the run command with a config file:

uv run cli.py run --config /path/to/config.yaml

The tool will:

• Run without any user interaction
• Log to migration.log
• Send Discord notifications (if configured)
• Handle errors gracefully

Dashboard

The Rich TUI dashboard shows:

• Global Progress Bar: Overall migration progress
• Accounts Table: Per-account status, progress, and statistics
• Status Panel: Elapsed time, throughput, totals
• Errors Panel: Recent errors (if any)

The dashboard updates in real-time and provides a clear view of the migration status.

Logging

Logs are written to:

• Console: Real-time output with Rich formatting
• File: migration.log with timestamps and structured logs

Discord Notifications

If configured, the tool sends Discord webhook messages for:

1. Migration Started: When migration begins
2. Migration Completed: When all migrations finish
3. Account Errors: When an account migration fails
4. Periodic Updates: Progress updates (if enabled)

Error Handling

• Individual message failures are tracked and logged
• Account-level errors are reported to Discord (if configured)
• Graceful shutdown on Ctrl+C
• Failed messages are counted but don't stop the migration

Project Structure

email_migrator/
├── migrator/
│   ├── __init__.py
│   ├── config.py          # Configuration management
│   ├── models.py           # Data models
│   ├── imap_client.py      # IMAP operations
│   ├── migration_worker.py # Migration logic
│   ├── dashboard.py        # Rich TUI dashboard
│   ├── discord_notifier.py # Discord webhooks
│   └── main.py             # Main orchestrator
├── cli.py                   # CLI interface
├── pyproject.toml          # Project configuration
├── config.example.yaml     # Example configuration
└── README.md               # This file

Development

Running Tests

# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests (if available)
uv run pytest

Code Style

The codebase uses:

• Type hints throughout
• Async/await for I/O operations
• Rich for terminal UI
• Clean architecture with separation of concerns

Troubleshooting

Connection Issues

• Verify IMAP server host and port
• Check SSL settings (use_ssl, verify_ssl)
• Ensure credentials are correct
• Check firewall/network settings

Migration Errors

• Check migration.log for detailed error messages
• Verify source and destination folders exist
• Ensure sufficient permissions on destination account
• Check Discord webhook URL if notifications fail

Performance

• Migration runs concurrently for all accounts
• Messages are migrated sequentially within each folder
• Large mailboxes may take significant time

License

This project is provided as-is for email migration purposes.

Contributing

Contributions are welcome! Please ensure:

• Code follows existing style
• Type hints are used
• Async operations are properly handled
• Error handling is comprehensive

Support

For issues or questions:

1. Check migration.log for errors
2. Validate configuration with check command
3. Review Discord notifications (if configured)