Hotmail/Outlook Email Bulk Deleter

An interactive CLI tool for bulk deleting emails from Hotmail/Outlook accounts using IMAP. Search by sender, date range, preview emails before deletion, and safely manage your inbox without complex API setup.

Features

• IMAP-based: No Azure/Graph API setup required
• Smart Filtering: Filter by sender (email or partial name) and date range
• Natural Language Dates: Use intuitive date formats like "between october 2024 - november 2024" or "in 2021"
• Preview Before Delete: See what will be deleted with sample emails and total count
• Safe: Requires explicit confirmation before any deletion
• Beautiful UI: Rich terminal output with colors, tables, and progress bars
• Multiple Sessions: Delete multiple batches in one run
• Resilient Connection: Automatically reconnects if IMAP drops with "Bad Socket"/broken pipe errors
• Error Handling: Graceful handling of connection issues and invalid inputs

Prerequisites

• Python 3.7 or higher
• A Hotmail/Outlook email account
• IMAP enabled in your Outlook settings
• An app password (not your regular password)

Installation

1. Clone or Download This Repository

cd outlook-email-deleter

2. Install Dependencies

pip install -r requirements.txt

Or install individually:

pip install python-dotenv rich dateparser

3. Enable IMAP in Outlook

1. Go to Outlook Settings
2. Navigate to Mail → Sync email
3. Under POP and IMAP, make sure Let devices and apps use IMAP is enabled
4. Click Save

4. Generate an App Password

Important: You MUST use an app password, not your regular email password.

For Microsoft/Outlook Accounts:

1. Go to Microsoft Security Settings
2. Sign in to your account
3. Under Advanced security options, find App passwords
4. Click Create a new app password
5. Copy the generated password (it will only be shown once)

Note: If you don't see the app passwords option:

• Make sure two-factor authentication (2FA) is enabled on your account
• Some organizational accounts may not support app passwords

Alternative Method:

If app passwords aren't available, you may need to:

1. Enable two-factor authentication first
2. Or check with your organization's IT department if it's a work account

5. Configure Credentials

1. Copy the example environment file:

   cp .env.example .env

2. Edit .env and add your credentials:

   IMAP_EMAIL=your_email@outlook.com
   IMAP_PASSWORD=your_app_password_here
   

   Replace:

   • your_email@outlook.com with your actual email address
   • your_app_password_here with the app password you generated

Usage

Run the Script

python3 email_deleter.py

Interactive Flow

1. Connection: Script connects to Outlook IMAP automatically

2. Sender Filter: Enter an email address or partial name

   • Example: newsletter@example.com
   • Example: LinkedIn
   • Press Enter to skip (search all senders)

3. Date Filter: Enter a date range using natural language

   • between october 2024 - november 2024
   • in 2021
   • before january 2023
   • after june 2025
   • Press Enter to skip (no date filter)

4. Preview: Review matching emails

   • See total count
   • View sample of 3-5 emails with date, sender, and subject
   • See what filters were applied

5. Confirm: Type yes to proceed or no to cancel

6. Delete: Watch progress bar as emails are deleted

7. Continue: Choose to start another deletion session or exit

Example Session

╭─────────────────────────────────────────────────────╮
│ Hotmail/Outlook Email Bulk Deleter                  │
│ Interactive CLI tool for managing your inbox        │
╰─────────────────────────────────────────────────────╯

✓ Successfully connected to Outlook IMAP server

======================================================================
New Deletion Session

Enter sender email or name
(e.g., 'newsletter@example.com' or 'LinkedIn'): LinkedIn

Enter date range
Examples:
  • between october 2024 - november 2024
  • in 2021
  • before january 2023
  • after june 2025
  • Press Enter to skip date filter

Date range: in 2024

╭─────────── Filters Applied ───────────╮
│ Search Criteria:                      │
│   Sender: LinkedIn                    │
│   Date Range: Jan 01, 2024 - Dec 31, │
│ 2024                                  │
╰───────────────────────────────────────╯

Found 47 email(s) matching your criteria

Showing sample of 5 email(s):

┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Date                 ┃ From            ┃ Subject                 ┃
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Mon, 15 Jan 2024     │ LinkedIn        │ You appeared in 5       │
│                      │                 │ searches this week      │
│ Thu, 25 Jan 2024     │ LinkedIn        │ New job opportunities   │
│ Sat, 10 Feb 2024     │ LinkedIn        │ Weekly digest           │
└──────────────────────┴─────────────────┴─────────────────────────┘

... and 42 more email(s)

⚠ WARNING: This will permanently delete 47 email(s)!

Do you want to proceed with deletion? [y/n]: y

Deleting emails... ━━━━━━━━━━━━━━━━━━━━━━━ 100% 47/47

✓ Successfully deleted 47 email(s)!

Do you want to delete more emails? [Y/n]:

Date Format Examples

The tool supports natural language date parsing:

Input	Meaning
between october 2024 - november 2024	Emails from Oct 1, 2024 to Nov 30, 2024
between jan 2023 and mar 2023	Emails from Jan 1, 2023 to Mar 31, 2023
in 2021	All emails in the year 2021
in march 2024	All emails in March 2024
before january 2023	All emails before Jan 1, 2023
after june 2025	All emails after Jun 1, 2025

Troubleshooting

Authentication Failed

Error: IMAP Error: [AUTHENTICATIONFAILED]

Solutions:

1. Make sure you're using an app password, not your regular password
2. Verify IMAP is enabled in Outlook settings
3. Check that your email and password in .env are correct
4. Try generating a new app password

IMAP Not Enabled

Error: Connection fails or times out

Solution: Follow the "Enable IMAP in Outlook" steps above

No Emails Found

If searches return 0 results:

• Try a broader sender filter (e.g., just domain name)
• Remove the date filter to search all dates
• Check if emails are in a different folder (script only searches INBOX)

Connection Timeout

• Check your internet connection
• Verify you can access outlook.office365.com
• Try running the script again (temporary network issues)

"Bad Socket" / Broken Pipe Errors

• The tool now auto-reconnects and retries the IMAP command when Outlook drops the connection with "Bad Socket" or similar errors
• If you see repeated failures, wait a moment and rerun; persistent errors can indicate a larger Outlook outage or local network issue

Safety Features

• Preview mode: Always shows what will be deleted before proceeding
• Explicit confirmation: Requires typing "yes" to delete
• Graceful interruption: Can press Ctrl+C to exit safely
• Error handling: Won't crash on individual email failures
• Read-only preview: Fetches email headers without marking as read

Technical Details

• IMAP Server: outlook.office365.com:993 (SSL)
• Mailbox: INBOX (default)
• Search: Server-side IMAP search (efficient, doesn't download all emails)
• Auto-reconnect: IMAP commands are retried after a transparent reconnect if the session is dropped mid-operation
• Deletion: Marks emails as deleted and expunges to permanently remove

Security Notes

• Never commit your .env file to version control
• Use app passwords instead of your main password
• The .gitignore file is configured to exclude .env
• Credentials are only stored locally in .env

Limitations

• Only works with INBOX folder (not subfolders)
• Requires IMAP to be enabled
• Some organizational accounts may restrict IMAP access
• App passwords may not be available without 2FA enabled

License

This tool is provided as-is for personal use. Use at your own risk.

Contributing

Feel free to submit issues, feature requests, or pull requests!

Disclaimer

This tool permanently deletes emails. Always review the preview carefully before confirming deletion. The authors are not responsible for any data loss.