Email Job Application Tracker

An automated Python solution for tracking job applications by analyzing emails from multiple accounts and updating a CSV tracking file.

Features

• Multi-Account Email Analysis: Connects to multiple email accounts via IMAP
• Intelligent Filtering: Filters out newsletters, spam, and non-job related emails
• AI-Powered Analysis: Uses OpenAI GPT-4o mini to analyze and classify job-related emails
• CSV Integration: Updates existing job tracking CSV with new information
• Smart Deduplication: Prevents processing the same email multiple times
• Comprehensive Logging: Detailed logging for debugging and monitoring
• Error Handling: Robust error handling and recovery mechanisms
• Parallel Processing: Efficient batch processing of emails

Email Classifications

The system can identify and classify the following types of job-related emails:

• application_submitted: Confirmation of job application submission
• interview_invitation: Interview scheduling requests
• rejection: Application rejection notifications
• offer: Job offers
• follow_up: Follow-up communications
• assessment: Technical assessments or tests
• reference_check: Reference check requests
• other: Other job-related communications

Prerequisites

• Python 3.8 or higher
• Email accounts with IMAP access enabled
• OpenAI API key
• Existing job tracking CSV file (or one will be created)

Installation

1. Clone or download this repository

2. Install required dependencies:

pip install -r requirements.txt

3. Create a .env file from the example:

cp .env.example .env

4. Edit .env and add your credentials:
   • OpenAI API key
   • Email account credentials
   • CSV file path (optional)

Email Account Setup

Gmail/UCSB Email

1. Enable IMAP in Gmail settings
2. For accounts with 2FA enabled, create an App-Specific Password:
   • Go to Google Account settings
   • Security → 2-Step Verification → App passwords
   • Generate a password for "Mail"
   • Use this password in the .env file

iCloud/me.com Email

1. Enable IMAP in iCloud settings
2. Generate an app-specific password:
   • Go to Apple ID settings
   • Sign-In & Security → App-Specific Passwords
   • Create a password for this application
   • Use this password in the .env file

Usage

Run the script:

python src/email_job_tracker.py

The script will:

1. Connect to both email accounts
2. Fetch emails since June 1, 2025
3. Filter out spam and newsletters
4. Analyze remaining emails with OpenAI
5. Update the CSV file with job-related information
6. Generate a summary report

Configuration

Environment Variables

• OPENAI_API_KEY: Your OpenAI API key (required)
• EMAIL1_ADDRESS: First email address (default: francesco.rosciano@me.com)
• EMAIL1_PASSWORD: Password for first email account (required)
• EMAIL2_ADDRESS: Second email address (default: francescorosciano@ucsb.edu)
• EMAIL2_PASSWORD: Password for second email account (required)
• JOB_TRACKER_CSV: Path to CSV file (default: Simplify_Tracked_Jobs_2025-07-06 (1).csv)

Customization

You can customize the filtering behavior by modifying the following in EmailConfig class:

• SPAM_DOMAINS: List of domains to filter out
• SPAM_KEYWORDS: Keywords indicating spam/newsletters
• JOB_KEYWORDS: Keywords indicating job-related emails
• FOLDERS_TO_SEARCH: Email folders to search

CSV File Structure

The script expects/creates a CSV with these columns:

• Job Title
• Company Name
• Job URL
• Applied Date
• Status
• Status Date
• Archived
• Date Archived
• Notes

Additional columns added by the script:

• Email Address
• Email Date
• Email Subject
• Email Classification
• Email Hash

Output

Logging

• Console output with progress information
• Detailed log file: email_job_tracker.log

CSV Updates

• New job entries are added for unmatched emails
• Existing entries are updated with new status information
• Notes are appended with email-derived information
• Backup created before each update

Cache

• email_cache.pkl: Stores processed email hashes to avoid reprocessing

Error Handling

The script handles various error scenarios:

• Connection failures
• Invalid credentials
• API rate limits
• Malformed emails
• CSV corruption

All errors are logged with full details for debugging.

Security Considerations

1. Never commit .env file: Add it to .gitignore
2. Use app-specific passwords: Don't use your main email password
3. Secure storage: Keep credentials encrypted if possible
4. API key safety: Protect your OpenAI API key
5. Regular backups: The script creates CSV backups automatically

Performance

• Processes emails in batches for efficiency
• Implements rate limiting for API calls
• Caches processed emails to avoid duplicates
• Parallel processing with configurable workers

Troubleshooting

Common Issues

1. Authentication Failed

   • Check email credentials
   • Ensure IMAP is enabled
   • Use app-specific passwords for 2FA accounts

2. No Emails Found

   • Check date range
   • Verify folder names
   • Check IMAP settings

3. API Errors

   • Verify OpenAI API key
   • Check API quota/limits
   • Review error logs

4. CSV Update Issues

   • Ensure write permissions
   • Check CSV format
   • Review backup files

Debug Mode

For more detailed output, modify the logging level in the script:

logging.basicConfig(level=logging.DEBUG, ...)

Maintenance

Regular Tasks

• Monitor log files for errors
• Clean up old backup files
• Update filtering rules as needed
• Review and adjust OpenAI prompts

Updating Dependencies

pip install --upgrade -r requirements.txt

License

This project is provided as-is for personal use. Ensure compliance with email provider terms of service and data protection regulations.

Support

For issues or questions:

1. Check the log file for detailed error messages
2. Review the troubleshooting section
3. Ensure all prerequisites are met
4. Verify configuration settings