# Boys' Email Daily Digest

Monitor children's email inboxes, log new messages, track sender frequency, and send daily digest summaries to each child's mom.

## Architecture

Single Python script (`/root/.hermes/scripts/boys-mail-monitor.py`) with three commands:

| Command | Schedule | Description |
|---|---|---|
| `collect` | Every 60m | Polls child inboxes for UNSEEN, logs to JSON, tracks senders |
| `summary` | Daily at 7 PM ET | Builds + sends daily digest HTML emails |
| `test-summary` | On-demand | Sends test digest to shonuff inbox for verification |

## Data files

| File | Purpose |
|---|---|
| `boys-mail.json` | Rolling log of all collected emails (30-day retention by timestamp) |
| `boys-senders.json` | Sender frequency database (count, first/last seen, flagged status) |

## Children and Recipients

| Child | Mom | Mom Email | BCC | Webmail |
|-------|-----|-----------|-----|---------|
| Garrison | Tina Brown | tinamichelle1008@gmail.com | g@germainebrown.com | webmail.iamgmb.com |
| Greyson | Kate Eubank | katherineeubank@gmail.com | g@germainebrown.com | webmail.iamgmb.com |

## IMAP polling details

- **Accounts:** Defined in `BOYS_ACCOUNTS` dict — each child has their own IMAP credentials on `heracles.mxrouting.net:993`
- **Fetch:** Uses `BODY.PEEK[]` to avoid marking messages as `\Seen` — boys' normal mail client still sees them as unread
- **Fallback:** If `BODY.PEEK[]` fails, falls back to `(RFC822)` which does mark as seen
- **Dedup:** Relies on IMAP UNSEEN state — a message is only returned once until someone marks it UNSEEN again

## Sender frequency tracking

- Every unique `from_email` gets a cumulative count, first/last seen timestamps, and a child association
- **High-volume alert:** Senders with `count >= HIGH_VOLUME_THRESHOLD` (default 3) get flagged in the database and highlighted amber in the summary
- **Name enrichment:** If a later email provides a display name for a previously-email-only sender, the name is updated

## Daily summary email

### HTML email structure

- **Title bar:** Red `border-bottom: 2px solid #dc2626` divider under child's name + date
- **Green "No new emails"** pill when inbox was quiet (`background: #f0fdf4, border: #bbf7d0`)
- **Email table** when there were new emails: From / Subject / Time columns
- **Top senders table** showing who's been emailing the most, with amber highlighting for high-volume senders
- **Signature:** Sho'Nuff full signature — red divider, circular SB badge, random title, random closing
- **Footer:** Information about frequency adjustments, phone login credentials (available on request), webmail link, and Sho'Nuff signature with unsubscribe assistance offer

### MIME structure

Both `text/plain` and `text/html` alternatives via `MIMEMultipart("alternative")`. Plain text has table-formatted content for email clients that don't render HTML.

## Sho'Nuff signature (applies to ALL emails from this system)

```html
<div style="border-top:2px solid #dc2626;margin-top:24px;padding-top:16px;">
<p style="font-size:12px;color:#999;margin:0 0 6px;">
<img src="https://core.itpropartner.com/shonuff-signature.svg" alt="SB" 
     style="width:40px;height:40px;border-radius:50%;vertical-align:middle;margin-right:8px;">
<strong style="color:#333;">Sho'Nuff Brown</strong><br>
<span style="color:#666;">{random_title} · shonuff@germainebrown.com</span>
</p>
<p style="font-size:12px;color:#888;font-style:italic;margin:8px 0 0;">_{random_closing}_</p>
</div>
```

**Rotating titles** (13): Operations Engineer, Infrastructure Mechanic, Digital Janitor, Systems Wrangler, Automation Specialist, Network Whisperer, Chief Problem Solver, Technical Fixer, Process Optimizer, Behind-the-Scenes Operator, Script Kiddie (Professional), Server Herder, Pipeline Plumber

**Rotating closings** (8): Smooth seas never made a skilled sailor., Keep your head on a swivel., Stay dangerous., The master has failed more times than the beginner has tried., Trust, but verify., Fortune favors the prepared., Not all who wander are lost., Done is better than perfect.

**SVG image location:** `https://core.itpropartner.com/shonuff-signature.svg`

## Introductory/Welcome Email

Sent on first setup to each mom explaining:
- Who Sho'Nuff is (assistant to Germaine)
- What the daily summary contains
- Offer to adjust frequency (reply to opt to weekly/etc.)
- Offer to provide phone login credentials
- Point to webmail URL
- Offer to unsubscribe from unwanted senders

## Cron

- collect: hourly (no_agent, zero LLM cost)
- summary: 7PM ET daily (no_agent, zero LLM cost)

## Pitfalls

- The first collection run finds ALL existing UNSEEN messages (backlog). This is correct — only new messages after that.
- Date parsing with timezone: `parsedate_to_datetime()` returns aware datetime. Use `.astimezone(timezone.utc)` not `.replace(tzinfo=timezone.utc)`.
- SMTP: uses `mail.germainebrown.com:2525` with STARTTLS (ports 25/465/587 blocked on netcup VPS).
- Email addresses populated after user provides them; script was written with placeholders initially. Update the `RECIPIENTS` dict when user provides real emails.