IMAP Sender Report

A Python script to audit IMAP mailboxes and export sender → recipient mappings with last occurrence dates.
Supports CSV, tab-delimited, and Excel (XLSX) output with autofilter, frozen header row, and auto-sized columns.

---

⚡ Quick Start

1. Install dependencies

   pip install openpyxl

2. Create one or more .ini config files
   See Configuration below.

3. Run the script

   python imap_sender_report.py mailbox1.ini mailbox2.ini

---

✨ Features

• Connects to any IMAP server (Office365, Gmail, etc.)
• Filters by target domain, date, and excluded sender domains
• Skips noisy folders (Junk, Spam, Trash, etc.)
• Exports to CSV, TAB, XLSX and/or JSON (configurable)
• Excel output includes:
  • Autofilter
  • Frozen header row
  • Auto-sized columns
  • Styled header
• JSON output includes:
  • Structured list of objects with from, to, and last_occurrence fields
  • UTF-8 encoding, indented for readability
• Per-mailbox logging
• Global summary table with:
  • Exported formats
  • Row counts
  • Duration per mailbox
  • Warnings for empty outputs

---

⚙️ Installation

Clone the repo and install dependencies:

pip install openpyxl

---

📄 Configuration

Each mailbox is defined in its own .ini file. Example:

[IMAP]
server = imap.example.com
port = 993
user = user@example.com
pass = yourpassword

[Filter]
target_domain = example.com
date_filter = SINCE 01-Nov-2025
excluded_sender_domains = noreply.example.com

[Folders]
exclude = Junk, Trash, Spam

[General]
progress_frequency = 500
output_formats = csv, tab, xlsx, json
excel_sheet = Mailflow
csv_delimiter = ,
date_format = %Y-%m-%d %H:%M:%S

See config_example_annotated.ini for detailed comments, or config_example_ini for a minimal template.

---

🚀 Usage

Run against one or more configs:

python imap_sender_report.py mailbox1.ini mailbox2.ini mailbox3.ini

Show help:

python imap_sender_report.py -h

Show version:

python imap_sender_report.py -v

---

📊 Example Output

Console summary at the end:

=== Export Summary (finished at 2025-11-27 12:50:12, total duration 0:02:15) ===
Mailbox (config)     | Formats              | Rows  | Duration
-----------------------------------------------------------------
mailbox1.ini         | CSV, TAB, XLSX       | 120   | 0:01:05
mailbox2.ini         | CSV, TAB             | 85    | 0:00:47
mailbox3.ini         | CSV                  | 12    | 0:00:23 ⚠️

---

📜 License

MIT License (Modified for Educational Use)
Copyright (c) 2025 Michel Sijmons – michel.sijmons.net

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, subject to the following conditions:

1. Attribution must be given to the original developer(s).
2. This Software is provided strictly for educational use only.
3. No claims are made regarding functionality, fitness for purpose, or accuracy.
4. The developer(s) shall not be held liable for any damages, losses, or issues arising from the use, misuse, or inability to use this Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND.

---

📝 Notes

• CSV and TAB exports work out of the box.
• XLSX export requires openpyxl.
• JSON export requires no extra dependencies (uses Python standard library).
• Logs are written per mailbox (imap_sender_report_<server>_<user>.log) and a global summary is appended to imap_sender_report.log.
• Designed for educational auditing use only.

---