A powerful desktop application for bulk downloading email attachments from Gmail and Outlook with advanced filtering, auto-renaming, and a modern GUI.
- Multi-Provider Support - Connect to Gmail or Outlook/Hotmail accounts
- Advanced Filtering - Filter emails by sender, subject, and date range
- File Type Selection - Choose which attachment types to download (PDF, images, documents, spreadsheets, etc.)
- Calendar Date Picker - Easy date selection with built-in calendar widget
- Auto-Rename Files - Multiple renaming patterns (date prefix, sender prefix, etc.)
- Preview Before Download - Review and select specific emails before downloading
- Progress Tracking - Real-time progress bar and detailed activity log
- Threaded Downloads - Fast parallel downloads without freezing the UI
- Modern Dark UI - Clean, professional interface built with CustomTkinter
+------------------------------------------+
| Email Attachment Downloader |
+------------------------------------------+
| Provider: [Gmail v] [?] |
| Email: [your.email@gmail.com ] |
| Password: [**************** ] |
| |
| [Connect] Status: Connected |
+------------------------------------------+
| Email Filters |
| From: [sender@example.com ] |
| Subject: [invoice ] |
| Date: [Start date] to [End date] |
+------------------------------------------+
| File Types |
| [x] PDF [x] IMAGES [x] DOCUMENTS |
| [x] SPREADSHEETS [x] PRESENTATIONS |
+------------------------------------------+
| [Search Emails] |
+------------------------------------------+
| Results: 45 emails, 127 attachments |
| [Preview Results] |
+------------------------------------------+
| Rename Pattern: [Date + Filename v] |
| [ ] Convert to lowercase |
+------------------------------------------+
| Save to: [C:/Downloads/Attachments] |
| [Download All Attachments] |
+------------------------------------------+
| Progress: [============== ] 70% |
| Downloading: invoice_march.pdf |
+------------------------------------------+
- Python 3.10 or higher
- pip (Python package manager)
-
Clone or download the repository
git clone https://github.com/yourusername/email-attachment-downloader.git cd email-attachment-downloader -
Install dependencies
pip install -r requirements.txt
-
Run the application
python main.py
Gmail requires an App Password for IMAP access (not your regular password).
-
Enable 2-Step Verification
- Go to Google Account Security
- Click on "2-Step Verification" and follow the setup
-
Generate an App Password
- Go to App Passwords
- Select "Mail" as the app
- Select your device
- Click "Generate"
- Copy the 16-character password
-
Enable IMAP (if not already enabled)
- Go to Gmail Settings
- Under "IMAP access", select "Enable IMAP"
-
Use in the app
- Select "Gmail" as provider
- Enter your Gmail address
- Paste the 16-character App Password (no spaces)
-
Using Regular Password (if 2FA is disabled)
- Simply use your regular Outlook password
-
Using App Password (if 2FA is enabled)
- Go to Microsoft Security
- Under "Additional security options", find "App passwords"
- Create a new app password
- Use this password in the app
-
Enable IMAP
- Go to Outlook.com Settings > Mail > Sync email
- Enable "Let devices and apps use IMAP"
- Select your email provider (Gmail or Outlook)
- Enter your email address
- Enter your App Password
- Click Connect
- From: Filter by sender email (e.g.,
invoices@company.com) - Subject: Filter by keywords in subject (e.g.,
invoice) - Date Range: Click the date buttons to open calendar picker
Check/uncheck the file types you want to download:
- Images (PNG, JPG, GIF, etc.)
- Documents (DOC, DOCX, TXT, etc.)
- Spreadsheets (XLS, XLSX, CSV)
- Presentations (PPT, PPTX)
- Archives (ZIP, RAR, 7Z)
Click Search Emails to find matching emails. The results will show:
- Number of emails found
- Total attachment count
Click Preview Results to:
- See a list of all matching emails
- Select/deselect specific emails
- View attachment names for each email
Choose a rename pattern:
| Pattern | Example Output |
|---|---|
| Keep Original | invoice.pdf |
| Date + Filename | 2024-01-15_invoice.pdf |
| Sender + Date + Filename | john_2024-01-15_invoice.pdf |
| Sender + Filename | john_invoice.pdf |
| Subject + Filename | Monthly_Report_data.xlsx |
- Set the download location (or use default)
- Click Download All Attachments
- Watch the progress bar and log
email_attachment_downloader/
├── main.py # Application entry point
├── requirements.txt # Python dependencies
├── README.md # This file
├── downloads/ # Default download folder
└── src/
├── __init__.py
├── email_client.py # IMAP connection & email fetching
├── downloader.py # Attachment extraction & saving
├── renamer.py # File renaming logic
├── date_picker.py # Calendar date picker widget
├── preview_window.py # Email preview/selection window
└── gui.py # Main GUI application
from src.email_client import EmailClient, EmailProvider
# Using context manager
with EmailClient(EmailProvider.GMAIL) as client:
client.connect('user@gmail.com', 'app_password')
emails = client.search_emails(
sender='invoices@company.com',
subject='invoice',
date_from=datetime(2024, 1, 1),
date_to=datetime(2024, 12, 31)
)
for email in emails:
print(f"{email.subject} - {email.attachment_count} attachments")from src.downloader import AttachmentDownloader
from src.renamer import create_renamer_from_template
# Create renamer with date prefix
renamer = create_renamer_from_template('date_filename')
# Create downloader
downloader = AttachmentDownloader(
download_dir='./downloads',
renamer=renamer,
allowed_extensions=['.pdf', '.xlsx']
)
# Download attachments
results = downloader.download_from_emails(emails)
for result in results:
if result.success:
print(f"Saved: {result.saved_filename}")
else:
print(f"Failed: {result.error}")Gmail:
- Make sure you're using an App Password, not your regular password
- Verify 2-Step Verification is enabled
- Check that IMAP is enabled in Gmail settings
Outlook:
- If 2FA is enabled, you must use an App Password
- Ensure IMAP is enabled in Outlook settings
- Check your internet connection
- Verify the email address is correct
- Try again in a few minutes (rate limiting)
- Check your filter settings (sender, subject, dates)
- Try with fewer filters first
- Verify the emails exist in your INBOX folder
- Check file type filters are enabled
- Ensure the download folder is writable
- Check the log for specific errors
| Package | Version | Purpose |
|---|---|---|
| customtkinter | >= 5.2.0 | Modern GUI framework |
| Pillow | >= 10.0.0 | Image handling |
| python-dateutil | >= 2.8.2 | Date parsing |
| tkcalendar | >= 1.6.1 | Calendar date picker |
- Your password is never stored - it's only kept in memory during the session
- Use App Passwords instead of your main password for better security
- The app only reads emails; it never modifies or deletes them
- All connections use SSL/TLS encryption (port 993)
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- CustomTkinter for the modern GUI framework
- tkcalendar for the calendar widget
If you encounter any issues or have questions:
- Check the Troubleshooting section
- Search existing Issues
- Open a new issue with:
- Your Python version
- Your operating system
- Steps to reproduce the problem
- Error messages from the log