Automated invoice download and processing system for Gmail. The script downloads invoices from email attachments, converts images to PDF, and organizes files for sending to the accountant.

• 🗓️ Configurable periods - previous month, current month, entire year, or custom range
• 📄 PDF and JPG support - automatic conversion of invoice photos to PDF
• 📝 Smart file naming - automatic naming with date and sender
• 📊 Collective preview - single PDF file for quick review of all invoices
• 🔍 Detailed logging - complete information about the download process
• ⚙️ Easy configuration - all settings in config.py file

• Python 3.7+
• Gmail account with API enabled
• Internet access

git clone <repository-url>
cd FVMerger

python -m venv venv

# Windows
venv\Scripts\activate

# macOS/Linux
source venv/bin/activate

pip install -r requirements.txt

1. Go to Google Cloud Console
2. Create a new project or select existing one
3. Enable Gmail API
4. Go to "Credentials" → "Create Credentials" → "OAuth 2.0 Client IDs"
5. Select "Desktop application"
6. Download JSON file and save as client_secret.json in project directory

python main.py

On first run, you'll be redirected to browser for Gmail access authorization.

# Default - previous month (perfect for sending to accountant by 10th of each month)
python main.py

# Current month
python main.py --period current_month

# Entire year
python main.py --period year

# Custom date range
python main.py --period custom --from 2025/01/01 --to 2025/03/31

# Help
python main.py --help

Edit config.py file to customize settings:

# Default download period
DEFAULT_PERIOD = "last_month"

# Directories
TEMP_DIR = "attachments"
JPG_TEMP = "jpg_temp"

# Gmail
CLIENT_SECRET_FILE = "client_secret.json"

# Message filters
EMAIL_FILTER = "-is:starred"

FVMerger/
├── main.py              # Main script
├── config.py            # Configuration
├── requirements.txt     # Python dependencies
├── README.md           # This documentation
├── client_secret.json  # Gmail API keys (you must add)
├── attachments/        # Downloaded invoices (separate files)
│   ├── 2025-07-15_orlen_Invoice_F_1498K19.pdf
│   └── 2025-08-12_siemens_statement_invoice.pdf
├── jpg_temp/          # Temporary files (automatically cleaned)
└── attachments.pdf    # Collective PDF for preview

# At the beginning of the month, download invoices from previous month
python main.py

# Check collective file
# → attachments.pdf

# Send separate files from attachments/ directory to accountant

python main.py --period current_month

python main.py --period year

python main.py --period custom --from 2025/01/01 --to 2025/03/31

# Remove old token and authorize again
rm gmail_token.json
python main.py

# Check if virtual environment is active
pip install -r requirements.txt

• Check if email contains PDF/JPG attachments
• Check filters in config.py (EMAIL_FILTER)
• Check date range

• Make sure JPG files are not corrupted
• Check if you have enough disk space

2025-08-15 23:12:19,716 - INFO - Period: last_month
2025-08-15 23:12:19,716 - INFO - Searching messages from: 2025/07/01 to: 2025/08/01
2025-08-15 23:12:19,716 - INFO - Found 4 messages
2025-08-15 23:12:19,716 - INFO - Processing message 1 from ORLEN PAY <orlenpay@orlen.pl>
2025-08-15 23:12:19,716 - INFO - Saved PDF: 2025-07-15_orlenpay_Invoice_F_1920K19.pdf
...

Hello, I'm sending the following documents in the attachment:

	1. 2025-07-15_orlenpay_Invoice_F_1920K19_0980_25_Orlen_Pay.pdf
	2. 2025-08-12_siemens_2025-08-12_INVOICES_01849_08_25_SLMLO_256131.pdf

Best regards
Kamil Kubicki

--- SUMMARY ---
Period: last_month (2025/07/01 - 2025/08/01)
Files found: 2
Files are located in directory: attachments/
Collective PDF (for preview): attachments.pdf

In case of problems:

1. Check "Troubleshooting" section
2. Run with --help to see all options
3. Check logs in console

Project for personal use.