IMAP Attachment Extractor

A Python script that connects to IMAP email servers to automatically extract and organize attachments from emails sent to or from specific email addresses.

Features

• IMAP Server Support: Connect to any IMAP server with SSL/TLS or STARTTLS encryption
• Email Filtering: Filter emails by sender or recipient address
• Date Filtering: Extract attachments from emails since a specific date
• Organized Storage: Automatically organize attachments into folders with YYYYMMDD_emailID_subject naming
• Multiple Configuration Options: Support for configuration files, command-line arguments, or interactive prompts
• Secure Authentication: Password prompts or configuration file support
• Duplicate Handling: Automatically handles duplicate attachment filenames
• Filename Sanitization: Safe handling of special characters in filenames

Requirements

• Python 3.6+
• Standard library modules only (no external dependencies)

Installation

1. Clone this repository:

git clone <repository-url>
cd imap-attachment-extractor

2. Make the script executable:

chmod +x imap_extractor.py

Configuration

Option 1: Configuration File (Recommended)

Copy the example configuration:

cp config.ini.example config.ini

Edit config.ini with your settings:

[imap]
# IMAP server configuration
server = imap.gmail.com
port = 993
ssl = true
starttls = false

# Authentication
username = your.email@gmail.com
password = your_password_here

# Email filtering
email_filter = target@domain.com
folder = INBOX
since_date = 2024-01-01

# Output settings
output_dir = ./attachments

Option 2: Command Line Arguments

python3 imap_extractor.py --server imap.gmail.com --username user@gmail.com --email-filter target@domain.com

Option 3: Interactive Mode

Simply run without arguments and follow the prompts:

python3 imap_extractor.py

Usage Examples

Basic Usage with Config File

python3 imap_extractor.py --config config.ini

Extract All Emails from Specific Address

python3 imap_extractor.py --config config.ini --email-filter john@company.com

Filter by Date Range

python3 imap_extractor.py --config config.ini --since-date 2024-01-01

STARTTLS Connection (Port 143)

python3 imap_extractor.py --server mail.example.com --port 143 --starttls --username user@example.com

Gmail with App Password

python3 imap_extractor.py --server imap.gmail.com --port 993 --username user@gmail.com --folder "INBOX.Sent Messages"

Command Line Options

Option	Description	Example
--config	Configuration file path	--config config.ini
--server	IMAP server hostname	--server imap.gmail.com
--port	IMAP server port	--port 993
--username	IMAP username	--username user@gmail.com
--password	IMAP password	--password mypassword
--email-filter	Target email address	--email-filter john@company.com
--folder	IMAP folder to search	--folder "INBOX.Sent Messages"
--since-date	Filter emails since date	--since-date 2024-01-01
--output-dir	Output directory	--output-dir ./downloads
--no-ssl	Disable SSL/TLS	--no-ssl
--starttls	Use STARTTLS	--starttls

Output Structure

Attachments are organized in folders with the following naming convention:

attachments/
├── 20240315_1439_Meeting_Notes/
│   ├── document.pdf
│   └── presentation.pptx
├── 20240316_1441_Invoice_Details/
│   └── invoice.jpg
└── 00000000_1512_No_Date_Email/
    └── attachment.docx

• YYYYMMDD: Email date in ISO format
• emailID: Unique email identifier
• subject: Sanitized email subject (truncated to 50 characters)

Common IMAP Server Settings

Gmail

server = imap.gmail.com
port = 993
ssl = true

Note: Requires App Password if 2FA is enabled

Outlook/Hotmail

server = outlook.office365.com
port = 993
ssl = true

Yahoo Mail

server = imap.mail.yahoo.com
port = 993
ssl = true

Custom/Corporate (STARTTLS)

server = mail.yourcompany.com
port = 143
ssl = false
starttls = true

Security Considerations

• Password Security: Passwords are prompted securely by default. Only store in config files if absolutely necessary.
• SSL/TLS: Always use encrypted connections when possible.
• File Permissions: Set restrictive permissions on configuration files containing passwords.
• App Passwords: Use app-specific passwords for services that support them (Gmail, Yahoo, etc.).

Troubleshooting

Common Issues

1. Connection Failed: Check server settings, port, and SSL/STARTTLS configuration
2. Authentication Error: Verify username/password, consider app passwords for Gmail
3. Folder Not Found: Use the interactive mode to see available folders
4. No Emails Found: Check email filter address and date range
5. Permission Denied: Ensure write permissions for output directory

Debug Mode

For troubleshooting, you can modify the script to add more verbose output by editing the print statements.

License

MIT License - feel free to use, modify, and distribute.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Support

For issues, questions, or feature requests, please open an issue on GitHub.

---

Disclaimer: This tool is designed for legitimate email management purposes. Always ensure you have proper authorization to access email accounts and comply with your organization's security policies.