imap-migration-tools 1.1.0

Tools for migrating IMAP emails

IMAP Email Migration Tools

Background

I was in need of migrating a Google account with more than 100,000 emails, and none of the freely available solutions worked reliably for me. They often timed out, crashed, or couldn't handle the volume. Hence, I created these simple, robust Python scripts that got the job done effectively.

Disclaimer

These scripts are provided "as is", without warranty of any kind, express or implied. While they have been tested and used successfully for ONE large migration, the author assumes no liability for any data loss, corruption, or other issues that may arise from their use. Users are advised to review the code and test with non-critical data before performing large-scale operations. No support or maintenance is guaranteed.

Project Overview

This repository contains a set of Python scripts designed to migrate emails between IMAP servers (supports Gmail, Outlook, etc.), verify the migration, and manage folder states.

The Scripts

1. migrate_imap_emails.py (The Solution)
   • Migrates emails folder-by-folder.
   • Multi-threaded: Uses a thread pool to copy messages in parallel for high speed.

• Smart De-duplication: Checks if a message already exists in the destination (matching Message-ID) and skips it if found.
• Robust: Preserves original dates and can preserve IMAP flags with --preserve-flags.
• Gmail Mode: For Gmail -> Gmail migrations, use --gmail-mode to migrate [Gmail]/All Mail (no duplicates) and apply Gmail labels by copying messages into label folders.
• Cleanup: Optionally deletes messages from the source after successful transfer (effectively a "Move" operation).
  • Improved for Gmail: Automatically detects "Trash" folders to ensure emails are properly binned rather than just archived.
• Sync Mode: Optionally deletes emails from destination that no longer exist in source (--dest-delete).
• Incremental Cache: Supports --migrate-cache <path> to store a local map of processed emails, drastically speeding up subsequent runs by skipping known messages.
• Configurable: Adjustable concurrency and batch sizes to respect server rate limits.

2. compare_imap_folders.py (The Validator)
   • Connects to both Source and Destination accounts.
   • Prints a side-by-side comparison table of message counts for every folder.

• Supports comparing IMAP to a local backup folder (.eml files) as either the source or destination.
• Essential for verifying that the migration was successful and that counts match.

3. count_imap_emails.py (The Investigator)

• Counts emails in all folders for a single IMAP account (initial assessment / sizing).
• Also supports counting a local backup folder (.eml files) via --path (or BACKUP_LOCAL_PATH).

4. backup_imap_emails.py (The Backup)

   • Downloads emails from an IMAP account to a local disk.
   • Format: Saves emails as individual .eml files (RFC 5322), compatible with Outlook, Thunderbird, and Apple Mail.
   • Structure: Replicates the IMAP folder hierarchy locally.
   • Incremental: Skips emails that have already been downloaded (based on UID) so you can run it periodically to fetch new messages.
   • Sync Mode: Optionally deletes local .eml files that no longer exist on the server (--dest-delete).
   • Gmail Labels Preservation: Creates a labels_manifest.json file mapping each email's Message-ID to its Gmail labels, enabling proper restoration with labels intact.

5. restore_imap_emails.py (The Restore)

   • Uploads emails from a local backup to an IMAP server.
   • Format: Reads .eml files and uploads them preserving original dates.
   • Structure: Recreates the folder hierarchy on the destination server.

• Incremental: Skips emails that already exist (based on Message-ID), but still syncs labels and flags.
• Sync Mode: Optionally deletes emails from destination that no longer exist in local backup (--dest-delete).
• Gmail Labels Restoration: Applies labels from labels_manifest.json to recreate the original Gmail label structure.

Getting Started

1. Prerequisites

• Python 3.9+

• No external installations required for basic (password) authentication. The scripts use only the Python Standard Library for standard IMAP login.

• Optional: OAuth2 authentication requires one additional package depending on your provider:

  • Microsoft (Outlook/Office 365): pip install msal
  • Google (Gmail): pip install google-auth-oauthlib

2. Installation

Clone this repository or download the script files to your local machine.

macOS

macOS often comes with Python, but it's best to install the latest version.

• Using Homebrew (Recommended):

  brew install python
  

• Manual: Download the installer from python.org.

Linux (Ubuntu/Debian)

Most Linux distributions come with Python 3 pre-installed. To ensure you have it:

sudo apt-get update
sudo apt-get install python3

Windows

1. Download the Python 3 executable installer from python.org.
2. Run the installer and ensure you check the box "Add Python to PATH" at the bottom of the setup screen before clicking Install.
3. Open PowerShell or Command Prompt and verify installation:

   python --version
   

Configuration & Running

You can configure the scripts using Environment Variables (recommended for security) or Command Line Arguments.

Method 1: Environment Variables

Linux / macOS (Bash/Zsh)

1. Set Variables:

   # Source Account
   export SRC_IMAP_HOST="imap.gmail.com"
   export SRC_IMAP_USERNAME="[e-mail]"
   export SRC_IMAP_PASSWORD="your-app-password"
   
   # Destination Account
   export DEST_IMAP_HOST="imap.destination.com"
   export DEST_IMAP_USERNAME="[e-mail]"
   export DEST_IMAP_PASSWORD="dest-app-password"
   
   # OAuth2 (Optional - instead of password)
   export SRC_OAUTH2_CLIENT_ID="your-client-id"
   export SRC_OAUTH2_CLIENT_SECRET="your-client-secret"  # Required for Google
   export DEST_OAUTH2_CLIENT_ID="your-dest-client-id"
   export DEST_OAUTH2_CLIENT_SECRET="your-dest-client-secret"  # Required for Google
   
   # Options (Optional)
   export DELETE_FROM_SOURCE="false"  # Set to "true" to delete from source after copy
   export DEST_DELETE="false"         # Set to "true" to delete orphans from destination (sync mode)
   export PRESERVE_FLAGS="false"      # Set to "true" to preserve IMAP flags (read/starred/etc)
   export GMAIL_MODE="false"          # Set to "true" for Gmail mode (All Mail + label application)
   export MAX_WORKERS=4               # Number of parallel threads
   export BATCH_SIZE=10               # Emails per batch
   

2. Run:

   python3 migrate_imap_emails.py
   

Windows (PowerShell)

1. Set Variables:

   # Source Account
   $env:SRC_IMAP_HOST="imap.gmail.com"
   $env:SRC_IMAP_USERNAME="[e-mail]"
   $env:SRC_IMAP_PASSWORD="your-app-password"
   
   # Same for DEST_* ...
   

2. Run:

   python migrate_imap_emails.py
   

Method 2: Command Line Arguments (Overrides)

All scripts support command-line arguments which take precedence over environment variables.

Migration:

python3 migrate_imap_emails.py \
  --src-host "imap.gmail.com" \
  --src-user "[e-mail]" \
  --src-pass "your-app-password" \
  --dest-host "imap.other.com" \
  --dest-user "[e-mail]" \
  --dest-pass "your-app-password" \
  --workers 4 \
  --src-delete

Comparison:

python3 compare_imap_folders.py \
  --src-host "imap.gmail.com" \
  --src-user "[e-mail]" \
  --src-pass "your-app-password" \
  --dest-host "imap.other.com" \
  --dest-user "[e-mail]" \
  --dest-pass "your-app-password"

# Compare IMAP source to a local backup folder
python3 compare_imap_folders.py \
  --src-host "imap.gmail.com" \
  --src-user "[e-mail]" \
  --src-pass "your-app-password" \
  --dest-path "./my_backup"

# Compare a local backup folder to an IMAP destination
python3 compare_imap_folders.py \
  --src-path "./my_backup" \
  --dest-host "imap.other.com" \
  --dest-user "[e-mail]" \
  --dest-pass "your-app-password"

Counting:

python3 count_imap_emails.py \
   --host "imap.gmail.com" \
   --user "[e-mail]" \
   --pass "secret"

# Count a local backup folder
python3 count_imap_emails.py \
   --path "./my_backup"

# Or via environment variable
export BACKUP_LOCAL_PATH="./my_backup"
python3 count_imap_emails.py

Counting (OAuth2):

python3 count_imap_emails.py \
   --host "imap.gmail.com" \
   --user "[e-mail]" \
   --oauth2-client-id "id" \
   --oauth2-client-secret "secret"

# Or via environment variables (single-account script)
export IMAP_HOST="imap.gmail.com"
export IMAP_USERNAME="[e-mail]"
export OAUTH2_CLIENT_ID="id"
export OAUTH2_CLIENT_SECRET="secret"  # Required for Google
python3 count_imap_emails.py

Backup:

python3 backup_imap_emails.py \
  --src-host "imap.gmail.com" \
  --src-user "[e-mail]" \
  --src-pass "your-app-password" \
  --dest-path "./my_backup"

Usage Examples

1. Full Migration

Migrate all folders from Source to Destination.

python3 migrate_imap_emails.py \
  --src-host "imap.gmail.com" \
  --src-user "[e-mail]" \
  --src-pass "source-app-password" \
  --dest-host "imap.other.com" \
  --dest-user "[e-mail]" \
  --dest-pass "dest-app-password"

1a. Gmail Mode Migration (Gmail -> Gmail)

For Gmail -> Gmail migrations, --gmail-mode migrates only [Gmail]/All Mail (no duplicates) and applies labels by copying messages into label folders.

python3 migrate_imap_emails.py \
  --gmail-mode \
  --src-host "imap.gmail.com" \
  --src-user "[e-mail]" \
  --src-pass "source-app-password" \
  --dest-host "imap.gmail.com" \
  --dest-user "[e-mail]" \
  --dest-pass "dest-app-password"

1b. Fast Incremental Migration (Cached)

Use a local cache file to remember processed emails. Use this for large migrations that may be interrupted or need to run multiple times.

python3 migrate_imap_emails.py \
  --src-host "imap.source.com" \
  --src-user "source" \
  --src-pass "pass" \
  --dest-host "imap.dest.com" \
  --dest-user "dest" \
  --dest-pass "pass" \
  --migrate-cache "./migration_cache"

To force a re-check of cached items without clearing the cache logic entirely, add --full-migrate.

1c. Preserve Flags (Any IMAP Server)

Preserve IMAP flags (\Seen, \Flagged, \Answered, \Draft) during migration.

If an email already exists on the destination (duplicate), the script can still sync missing flags on the existing message.

python3 migrate_imap_emails.py \
  --preserve-flags \
  --src-host "imap.example.com" \
  --src-user "[e-mail]" \
  --src-pass "source-password" \
  --dest-host "imap.example.com" \
  --dest-user "[e-mail]" \
  --dest-pass "dest-password"

2. Single Folder Migration

Migrate ONLY a specific folder (e.g., trying to fix just "Important" or "Sent").

# Syntax: python3 migrate_imap_emails.py "[Folder Name]"
python3 migrate_imap_emails.py \
  --src-host "imap.gmail.com" \
  --src-user "[e-mail]" \
  --src-pass "source-app-password" \
  --dest-host "imap.other.com" \
  --dest-user "[e-mail]" \
  --dest-pass "dest-app-password" \
  "[Gmail]/Important"

3. Move Instead of Copy

Migrate and delete from source immediately after verifying the copy.

# Using flag
python3 migrate_imap_emails.py \
  --src-host "imap.gmail.com" \
  --src-user "[e-mail]" \
  --src-pass "source-app-password" \
  --dest-host "imap.other.com" \
  --dest-user "[e-mail]" \
  --dest-pass "dest-app-password" \
  --src-delete

# Or specific folder with delete
python3 migrate_imap_emails.py \
  --src-host "imap.gmail.com" \
  --src-user "[e-mail]" \
  --src-pass "source-app-password" \
  --dest-host "imap.other.com" \
  --dest-user "[e-mail]" \
  --dest-pass "dest-app-password" \
  "INBOX" \
  --src-delete

4. Sync Mode (Delete from Destination)

Keep destination in sync by deleting emails that no longer exist in the source.

Note: --dest-delete is not supported in --gmail-mode.

# Migration: Delete destination emails not found in source
python3 migrate_imap_emails.py \
  --src-host "imap.gmail.com" \
  --src-user "[e-mail]" \
  --src-pass "source-app-password" \
  --dest-host "imap.other.com" \
  --dest-user "[e-mail]" \
  --dest-pass "dest-app-password" \
  --dest-delete

# Backup: Delete local .eml files not found on server
python3 backup_imap_emails.py \
  --src-host "imap.gmail.com" \
  --src-user "[e-mail]" \
  --src-pass "source-app-password" \
  --dest-path "./backup" \
  --dest-delete

# Restore: Delete server emails not found in local backup
python3 restore_imap_emails.py \
  --src-path "./backup" \
  --dest-host "imap.other.com" \
  --dest-user "[e-mail]" \
  --dest-pass "dest-app-password" \
  --dest-delete

Warning: The --dest-delete flag permanently removes emails/files from the destination. Use with caution and always verify your backup is complete before enabling this option.

5. Verify Migration

Compare counts between source and destination.

python3 compare_imap_folders.py \
  --src-host "imap.gmail.com" \
  --src-user "[e-mail]" \
  --src-pass "source-app-password" \
  --dest-host "imap.other.com" \
  --dest-user "[e-mail]" \
  --dest-pass "dest-app-password"

# IMAP source -> local backup destination
python3 compare_imap_folders.py \
  --src-host "imap.gmail.com" \
  --src-user "[e-mail]" \
  --src-pass "source-app-password" \
  --dest-path "./my_backup"

# local backup source -> IMAP destination
python3 compare_imap_folders.py \
  --src-path "./my_backup" \
  --dest-host "imap.other.com" \
  --dest-user "[e-mail]" \
  --dest-pass "dest-app-password"

Output Example:

Folder Name             | Source Count | Dest Count | Status
------------------------------------------------------------
INBOX                   | 1250         | 1250       | MATCH
...

6. Local Backup

Download all your emails to your computer as .eml files.

# Backup all folders from an IMAP account to a local folder
python3 backup_imap_emails.py \
  --src-host "imap.gmail.com" \
  --src-user "[e-mail]" \
  --src-pass "your-app-password" \
  --dest-path "./backup_folder"

# Or via command line
python3 backup_imap_emails.py \
  --src-host "imap.gmail.com" \
  --src-user "[e-mail]" \
  --src-pass "your-app-password" \
  --dest-path "/Users/jdoe/Documents/Emails"

# Backup single folder
python3 backup_imap_emails.py \
  --src-host "imap.gmail.com" \
  --src-user "[e-mail]" \
  --src-pass "your-app-password" \
  --dest-path "./my_backup" \
  "[Gmail]/Sent Mail"

6a. Compare IMAP vs Local Backup

Use compare_imap_folders.py to validate an IMAP account against a local backup created by backup_imap_emails.py.

# Option 1: IMAP source -> local destination
python3 compare_imap_folders.py \
  --src-host "imap.gmail.com" \
  --src-user "[e-mail]" \
  --src-pass "your-app-password" \
  --dest-path "./my_backup"

# Option 2: local source -> IMAP destination
python3 compare_imap_folders.py \
  --src-path "./my_backup" \
  --dest-host "imap.other.com" \
  --dest-user "[e-mail]" \
  --dest-pass "your-app-password"

You can also set local paths via environment variables:

export SRC_LOCAL_PATH="./my_backup"
export DEST_LOCAL_PATH="./my_backup"

6b. Count a Local Backup

Use count_imap_emails.py to get per-folder counts from a local backup created by backup_imap_emails.py.

# Option 1: explicit path
python3 count_imap_emails.py --path "./my_backup"

# Option 2: environment variable
export BACKUP_LOCAL_PATH="./my_backup"
python3 count_imap_emails.py

7. Gmail Backup with Labels Preservation

When backing up a Gmail account, use --gmail-mode for the recommended workflow. This backs up [Gmail]/All Mail (no duplicates) and creates a labels manifest for restoration.

# Recommended: Use --gmail-mode for simplest workflow
python3 backup_imap_emails.py \
  --src-host "imap.gmail.com" \
  --src-user "[e-mail]" \
  --src-pass "your-app-password" \
  --dest-path "./gmail_backup" \
  --gmail-mode

This is equivalent to the more verbose:

python3 backup_imap_emails.py \
  --src-host "imap.gmail.com" \
  --src-user "[e-mail]" \
  --src-pass "your-app-password" \
  --dest-path "./gmail_backup" \
  --preserve-labels \
  "[Gmail]/All Mail"

For large accounts (100K+ emails), you can build the manifest first to test:

# Step 1: Build manifest only (fast, no download)
python3 backup_imap_emails.py \
  --src-host "imap.gmail.com" \
  --src-user "[e-mail]" \
  --src-pass "your-app-password" \
  --dest-path "./gmail_backup" \
  --manifest-only

# Step 2: Download emails (can run later, manifest already exists)
python3 backup_imap_emails.py \
  --src-host "imap.gmail.com" \
  --src-user "[e-mail]" \
  --src-pass "your-app-password" \
  --dest-path "./gmail_backup" \
  "[Gmail]/All Mail"

How it works:

1. The script scans ALL folders in your Gmail account to identify which emails have which labels
2. Creates a labels_manifest.json file mapping each email's Message-ID to its labels and IMAP flags
3. Downloads all emails from [Gmail]/All Mail (contains every email once, no duplicates)

Example labels_manifest.json:

{
  "<[e-mail]>": {
    "labels": ["INBOX", "Work", "Projects/2024"],
    "flags": ["\\Seen"]
  },
  "<[e-mail]>": {
    "labels": ["Sent Mail", "Personal"],
    "flags": ["\\Seen", "\\Flagged"]
  }
}

Preserved IMAP Flags:

• \Seen - Email has been read
• \Flagged - Email is starred/flagged
• \Answered - Email has been replied to
• \Draft - Email is a draft

Benefits:

• ✅ No duplicate emails on disk (each email saved once)
• ✅ Labels are preserved for restoration
• ✅ Read/unread and starred status is preserved
• ✅ Includes system labels (INBOX, Sent Mail, Starred) and user labels
• ✅ Progress reporting for large accounts

Note: Gmail labels like "Important" that are auto-managed by Gmail are excluded from the manifest as they cannot be reliably restored.

8. Backup with Flags Only (Non-Gmail)

For non-Gmail servers, you can preserve read/starred status with --preserve-flags:

python3 backup_imap_emails.py \
  --src-host "imap.example.com" \
  --src-user "[e-mail]" \
  --src-pass "your-password" \
  --dest-path "./my_backup" \
  --preserve-flags \
  "INBOX"

This creates a flags_manifest.json with the status of each email.

9. Restore Backup to IMAP Server

Restore emails from a local backup to any IMAP server.

By default, restore runs in incremental mode: it uploads only emails that are not already present on the destination (based on Message-ID). Use --full-restore to force the legacy behavior (process all emails and re-sync labels/flags for already-present messages).

# Restore all folders from backup
python3 restore_imap_emails.py \
  --src-path "./my_backup" \
  --dest-host "imap.gmail.com" \
  --dest-user "[e-mail]" \
  --dest-pass "your-app-password"

# Force full restore (legacy behavior)
python3 restore_imap_emails.py \
  --src-path "./my_backup" \
  --dest-host "imap.gmail.com" \
  --dest-user "[e-mail]" \
  --dest-pass "your-app-password" \
  --full-restore

# Restore with flags (read/starred status)
python3 restore_imap_emails.py \
  --src-path "./my_backup" \
  --dest-host "imap.example.com" \
  --dest-user "[e-mail]" \
  --dest-pass "your-password" \
  --apply-flags

# Restore a specific folder
python3 restore_imap_emails.py \
  --src-path "./my_backup" \
  --dest-host "imap.gmail.com" \
  --dest-user "[e-mail]" \
  --dest-pass "your-app-password" \
  "INBOX"

10. Gmail Restore with Labels

Restore a Gmail backup with full label structure using --gmail-mode:

python3 restore_imap_emails.py \
  --src-path "./gmail_backup" \
  --dest-host "imap.gmail.com" \
  --dest-user "[e-mail]" \
  --dest-pass "your-app-password" \
  --gmail-mode

How Gmail restore works:

1. Reads emails from the backup (typically [Gmail]/All Mail)
2. Uploads each email to the first usable label folder (preserving original flags)

• If an email has no usable labels, it is uploaded to Restored/Unlabeled

3. Looks up the Message-ID in labels_manifest.json
4. Copies the email to each label folder (e.g., "Work", "Personal", "Projects/2024")

Alternatively, restore folders individually with labels and flags applied:

python3 restore_imap_emails.py \
  --src-path "./gmail_backup" \
  --dest-host "imap.gmail.com" \
  --dest-user "[e-mail]" \
  --dest-pass "your-app-password" \
  --apply-labels \
  --apply-flags

OAuth2 Authentication

All scripts support OAuth2 as an alternative to password-based authentication. The OAuth2 provider is auto-detected from the IMAP host:

IMAP Host contains	Detected Provider
outlook, office365, microsoft	Microsoft
gmail, google	Google

To use OAuth2, pass --oauth2-client-id (or --src-oauth2-client-id/--dest-oauth2-client-id for dual-account scripts) instead of the password argument.

Environment variable equivalents:

• Dual-account scripts: SRC_OAUTH2_CLIENT_ID, SRC_OAUTH2_CLIENT_SECRET and DEST_OAUTH2_CLIENT_ID, DEST_OAUTH2_CLIENT_SECRET.
• Single-account scripts (like count_imap_emails.py): OAUTH2_CLIENT_ID, OAUTH2_CLIENT_SECRET (also accepts SRC_OAUTH2_CLIENT_ID, SRC_OAUTH2_CLIENT_SECRET).

Microsoft (Outlook / Office 365)

Requires the msal package (pip install msal). Uses the device code flow — no browser redirect needed. The tenant ID is auto-discovered from the user's email domain.

Creating an App Registration in Microsoft Entra

1. Go to Microsoft Entra admin center → Identity → Applications → App registrations
2. Click New registration
   • Name: e.g., "IMAP Migration Tool"
   • Supported account types: Select based on your needs (single tenant or multi-tenant)
   • Redirect URI: Leave blank (not needed for device code flow)
3. Click Register
4. Copy the Application (client) ID — this is your --oauth2-client-id

Adding API Permissions

1. In your app registration, go to API permissions
2. Click Add a permission → APIs my organization uses
3. Search for and select Office 365 Exchange Online
4. Select Delegated permissions
5. Check IMAP.AccessAsUser.All
6. Click Add permissions
7. (Optional) Click Grant admin consent if you have admin rights and want to pre-approve for all users

Enabling Public Client Flow

1. Go to Authentication
2. Under Advanced settings, set Allow public client flows to Yes
3. Click Save

Usage

# Install dependency
pip install msal

# Migration with Microsoft OAuth2 on source
python3 migrate_imap_emails.py \
  --src-host "outlook.office365.com" \
  --src-user "[e-mail]" \
  --src-oauth2-client-id "your-azure-app-client-id" \
  --dest-host "imap.other.com" \
  --dest-user "[e-mail]" \
  --dest-pass "password"

The script will print a device code and URL. Open the URL in a browser, enter the code, and sign in to authorize access.

Google (Gmail)

Requires the google-auth-oauthlib package (pip install google-auth-oauthlib). Uses the installed app flow — opens a browser window for consent. Both --oauth2-client-id and --oauth2-client-secret are required.

# Install dependency
pip install google-auth-oauthlib

# Backup with Google OAuth2
python3 backup_imap_emails.py \
  --src-host "imap.gmail.com" \
  --src-user "[e-mail]" \
  --src-oauth2-client-id "your-google-client-id" \
  --src-oauth2-client-secret "your-google-client-secret" \
  --dest-path "./gmail_backup"

The script will open your default browser for Google sign-in. After authorizing, the token is returned automatically via a local HTTP redirect.

Troubleshooting

• "Too many simultaneous connections": IMAP servers (especially Gmail) limit the number of active connections per IP or user (typically ~15). Since migrate_imap_emails.py uses multiple threads, you may hit this limit. Solution: Reduce MAX_WORKERS to 4 or 2 using the environment variable.

• Authentication Errors: If you are using Gmail or Google Workspace, you generally cannot use your regular login password. You must enable 2-Step Verification and generate an App Password. Use that App Password in the _PASSWORD variable.

• Timeouts / Socket Errors: Migrating 100k+ emails is network intensive. If the script crashes, simply run it again. The built-in de-duplication will skip already migrated messages and resume where it left off.

Gmail "All Mail" & Deletion

If you are migrating from a Gmail account and using the --src-delete option:

• The script attempts to detect your Trash folder (e.g., [Gmail]/Trash or [Gmail]/Bin).
• Instead of simply marking emails as deleted (which Gmail often treats as "Archive"), the script copies the email to the Trash folder and then marks the original as deleted.
• This ensures that the storage count in [Gmail]/All Mail actually decreases, as the emails are moved to the Trash (which is auto-emptied by Google after 30 days) rather than remaining in your "All Mail" archive.

Development & Testing

Setting Up the Development Environment

1. Clone the repository:

   git clone https://github.com/JCallico/imap-migration-tools.git
   cd imap-migration-tools
   

2. Create a virtual environment:

   python3 -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. Install development dependencies:

   pip install -r requirements.txt
   # Or using Make:
   make install-dev
   

Running Tests

The project uses pytest for testing with a custom mock IMAP server for integration tests.

# Run all tests
make test

# Run tests with verbose output
PYTHONPATH=src pytest test/ -v

# Run tests with coverage report
make coverage

# Run a specific test file
PYTHONPATH=src pytest test/test_migrate_imap_emails.py -v

# Run a specific test
PYTHONPATH=src pytest test/test_imap_common.py::TestNormalizeFolderName -v

Code Quality

# Run linter
make lint

# Auto-format code
make format

# Check formatting without modifying
make format-check

# Run security scan
make security

# Run type checker
make typecheck

# Run all CI checks locally
make ci

Test Structure

Test File	Description
test_migrate_imap_emails.py	Email migration tests (basic, duplicates, deletion, folders)
test_backup_imap_emails.py	Backup functionality tests
test_restore_imap_emails.py	Restore functionality tests
test_count_imap_emails.py	Email counting tests
test_compare_imap_folders.py	Folder comparison tests
test_imap_common.py	Shared utility function tests

Continuous Integration

The project uses GitHub Actions for CI. On every push and pull request:

• Lint: Code style and formatting checks (Ruff)
• Test: Runs on Python 3.9, 3.10, 3.11, 3.12, and 3.13
• Security: Bandit security scanner
• Type Check: mypy static type analysis

License

This project is licensed under the MIT License - see the LICENSE file for details.