HOA Mail Summarizer

Python • Gmail API • Automation — Summarizes HOA notices, extracts violations by address & type, and exports monthly reports.

Overview

Automate HOA inbox triage: this tool connects to Gmail (read‑only), pulls messages from PMs/HOAs, and structures them into a violation ledger with address, category, dates, and status. Export to CSV/Excel, or generate monthly rollups for your property dashboard.

Filters HOA emails using sender + subject patterns and labels.
Extracts key fields: address, violation type, opened/due dates, status, cost/quote.
Deduplicates threads and groups by property & month.
Exports: CSV/Excel (pivot‑ready) and Markdown summaries.

Screenshots

Place your images at /assets/hoa/ to update these thumbnails.

Setup (Gmail API, local run)

Create a Google Cloud project → enable Gmail API → create OAuth Desktop App credentials → download client_secret.json.
Install dependencies:

pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib pandas python-dotenv dateparser

Put client_secret.json in your project folder. First run opens a browser for consent and saves token.json.
Create a .env (optional) for label filters and senders.

# .env
GMAIL_QUERY=(label:INBOX OR label:HOA) from:(support@ncfindahome.com OR management@example.com)
DATE_SINCE=2025-01-01
EXPORT_DIR=exports

Usage

python summarize_hoa.py --since 2025-01-01 --out exports/hoa_violations_2025-10.csv

Add --month 2025-10 to force a month rollup. Use Windows Task Scheduler or cron to run weekly.

# summarize_hoa.py (core outline)
from gmail_client import fetch_messages
from parsers import parse_violation
import pandas as pd

msgs = fetch_messages(query)
rows = [parse_violation(m) for m in msgs]
df = pd.DataFrame([r for r in rows if r])
# dedupe by (address, type, threadId)
df = df.sort_values('date').drop_duplicates(['address','type','threadId'], keep='last')
df.to_csv('exports/hoa_violations.csv', index=False)

Output Columns

address — standardized (e.g., 11111 Travis Gulch Dr, Charlotte, NC)
type — exterior / trash bin / lawn / parking / noise / other
opened, due, resolved — ISO dates
status — open / scheduled / completed / appealed
cost — numeric, parsed from quotes
threadId, messageId, sender, subject
month — YYYY‑MM for pivoting

Privacy & Permissions

This tool requests minimal, read‑only Gmail scopes and stores tokens locally in token.json. You can revoke access anytime from your Google Account → Security → Third‑party access. Never commit token files to Git.

Download & Run

Clone: git clone https://github.com/stephen-n-zhou/hoa-mail-summarizer
Install dependencies (see above).
Run the script and check /exports for CSV/Excel.

Want a GUI? Next milestone adds a simple web UI to preview threads and confirm parsed fields before export.

Roadmap

One‑click Windows Task Scheduler job / cron template
Rules editor for address normalization and type mapping
Attachment saving + image OCR (optional)
Dashboard: per‑property monthly trend charts

FAQ

Will this mark emails as read or move them?

No. It uses read‑only scopes unless you opt in to labeling (write scopes).

Can I export to Excel pivot with month columns?

Yes — export CSV and open in Excel; or extend the script to produce an .xlsx with a PivotTable.

How do I avoid re‑processing old threads?

Use --since and persist a seen_threads.json cache file keyed by threadId.