House File Stats

What it does

A dashboard of the email house file in Constant Contact: file size, how much of it is mailable, field completeness, per-source totals and sync freshness, public newsletter list sizes, a state and ZIP map, and growth over time. A collector pages through every contact each morning and keeps only counters.

Privacy is the design, not an afterthought. Contacts are held only in memory; the output is counts and percentages. Small ZIP codes are folded into state totals, internal list names stay off the page, and the workflow fails the run if anything resembling an email, phone number, or record ID appears in the output. Another organization can reuse it by editing one config file.

What it can do

• Daily aggregate stats and a growth history committed as JSON
• Field completeness with address fallbacks to custom fields
• Per-source attribution, with "last record created" to show a sync is still landing
• State and ZIP map with small-count suppression and masking
• Privacy guard in the workflow that fails on personal data
• Optional ZIP-to-state fixer, dry run by default
• One config.yml holds everything account-specific

Make it your own

Start by forking the repository into your own organization. Everything below assumes you are working in your fork, not this one.

1. Fork the repo and create a Constant Contact developer app with the contact_data and offline_access scopes.
2. Copy .env.example to .env, fill in the client id and secret, and run python authorize.py once for a refresh token.
3. Edit config.yml: title, source systems and how to recognize them, public lists, and address fallback fields.
4. Add the three secrets to Actions, enable Pages from main, folder /docs, and replace docs/CNAME.
5. Run the workflow once by hand. Keep the dashboard out of search engines; the included robots.txt and meta tags do that.

Stuck on a step? Open an issue on the repository. Questions from people adapting these for their own institution are the most useful feedback we get.