Email Summarizer + Contact Profiler#

Three independent stages — run any subset depending on what you need:

text

[Data Source]          [Analysis]          [Delivery]
fetch_imap.py    ──→                ──→
parse_file.py    ──→  build_report.py ──→  send_report.py
                       → .html + .xlsx

Each stage reads from / writes to files (or stdin/stdout), so they compose freely.

---

Installation#

bash

# Python dependencies
pip install -r requirements.txt

# Node.js dependency (only for native .pst parsing)
cd scripts && npm install && cd ..

---

Script Reference#

Stage 1 — Data Source#

fetch_imap.py — Fetch emails from a live IMAP mailbox

bash

export EMAIL_USER=you@163.com
export EMAIL_PASS=your-app-password

# Fetch last 7 days (inbox only) → emails.json
python3 scripts/fetch_imap.py --days 7 --output emails.json

# Fetch a date range, inbox + sent
python3 scripts/fetch_imap.py --since 2026-03-01 --until 2026-03-28 \
    --with-sent --preset 163 --output emails.json

# Pipe directly to build_report.py (no intermediate file)
python3 scripts/fetch_imap.py --days 30 | python3 scripts/build_report.py --output report

FlagDefaultDescription--days N7Fetch last N days. Ignored if --since is set.--since DATE—Start date inclusive (YYYY-MM-DD)--until DATE—End date exclusive (YYYY-MM-DD, default: today)--max N200Max emails per folder--folder NAMEINBOXInbox folder name--preset NAME163Mailbox preset: 163 | qq | exmail | gmail | outlook``--with-sentoffAlso fetch Sent folder (recommended for relationship analysis)--output FILEstdoutWrite JSON to file; prints to stdout if omitted

Supported presets:

PresetIMAP ServerSent folder163imap.163.com:993已发送qqimap.qq.com:993Sent Messagesexmailimap.exmail.qq.com:993Sent Messagesgmailimap.gmail.com:993[Gmail]/Sent Mailoutlookoutlook.office365.com:993Sent Items

---

parse_file.py — Parse a local email export

bash

# Parse a .pst file (native engine, no system install needed)
python3 scripts/parse_file.py --pst ~/Downloads/archive.pst --output emails.json

# Parse a .mbox file (inbox + sent)
python3 scripts/parse_file.py --mbox Inbox.mbox --sent-mbox Sent.mbox --output emails.json

# Parse a folder of .msg files, filter by date
python3 scripts/parse_file.py --msg-dir ./exported/ --since 2026-01-01 --output emails.json

# Pipe to build_report.py
python3 scripts/parse_file.py --pst archive.pst | python3 scripts/build_report.py --output report

FlagDefaultDescription--pst FILE—Outlook .pst archive--mbox FILE—Unix mbox file--msg-dir DIR—Folder of .msg files--sent-mbox FILE—Additional sent-items mbox (with --mbox)--pst-engineautoauto | native | readpst``--days NallOnly include last N days--since DATE—Start date inclusive (YYYY-MM-DD)--until DATE—End date exclusive (YYYY-MM-DD)--max N500Max emails to load--output FILEstdoutWrite JSON to file; prints to stdout if omitted

PST engines:

EngineFlagRequiresNative (default)--pst-engine native``cd scripts && npm installReadpst--pst-engine readpst``apt install pst-utils or brew install libpstAuto--pst-engine autoTries native first, falls back to readpst

---

Stage 2 — Analysis#

build_report.py — Analyse emails → HTML + Excel report

bash

# From a file
python3 scripts/build_report.py --input emails.json --output report

# Specify owner explicitly (when analysing someone else's PST)
python3 scripts/build_report.py --input emails.json --output report \
    --owner xiang-xiang.hu@connect.polyu.hk

# From stdin (piped from Stage 1)
python3 scripts/fetch_imap.py --days 30 | python3 scripts/build_report.py --output report

FlagDefaultDescription--input FILEstdinPath to emails JSON from Stage 1--output PREFIXcontact_reportOutput path prefix. Writes <prefix>.html and <prefix>.xlsx``--owner EMAILauto-inferredMailbox owner address. Auto-detected if omitted.

Output files:

• <prefix>.html — self-contained HTML report (open in browser or attach to email)
• <prefix>.xlsx — Excel spreadsheet with the same data

Report columns: # / Preferred Name / Email / Company / Position / Subject Summary / Source / Emails (Recv/Sent)

---

Stage 3 — Delivery#

send_report.py — Send report files via SMTP

bash

export EMAIL_USER=you@163.com
export EMAIL_PASS=your-app-password

# Send HTML + Excel to a recipient
python3 scripts/send_report.py \
    --html report.html --xlsx report.xlsx --to friend@example.com

# Send to yourself (EMAIL_USER)
python3 scripts/send_report.py --html report.html --xlsx report.xlsx

# HTML only (no attachment)
python3 scripts/send_report.py --html report.html --to friend@example.com

# Custom subject
python3 scripts/send_report.py --html report.html --subject "March Contact Report"

FlagDefaultDescription--html FILErequiredHTML file to use as email body--xlsx FILE—Excel file to attach (optional)--to ADDREMAIL_USERRecipient address--subject STRautoEmail subject (auto-generated if omitted)--preset NAME163SMTP preset: 163 | qq | exmail | gmail | outlook

---

Private library modules (not standalone scripts)#

FileProvides_core.py``decode_header, parse_addr, get_domain, strip_html, html_esc, get_body``_analyze.py``infer_owner, build_contacts, domain/company/position/name inference_render.py``build_report_html, build_excel, SMTP_MAP

---

Complete workflow examples#

A — IMAP mailbox → report → send to self#

bash

export EMAIL_USER=you@163.com
export EMAIL_PASS=your-app-password

python3 scripts/fetch_imap.py --days 30 --with-sent --output /tmp/emails.json
python3 scripts/build_report.py --input /tmp/emails.json --output /tmp/report
python3 scripts/send_report.py --html /tmp/report.html --xlsx /tmp/report.xlsx --preset 163

B — PST file → report → send to someone#

bash

python3 scripts/parse_file.py --pst ~/Downloads/archive.pst --output /tmp/emails.json
python3 scripts/build_report.py --input /tmp/emails.json --output /tmp/report
EMAIL_USER=sender@163.com EMAIL_PASS=xxx \
  python3 scripts/send_report.py --html /tmp/report.html --xlsx /tmp/report.xlsx \
    --to recipient@example.com

C — One-liner (pipe, no intermediate files)#

bash

python3 scripts/parse_file.py --pst archive.pst \
  | python3 scripts/build_report.py --output /tmp/report

D — Report only, no email (open locally)#

bash

python3 scripts/parse_file.py --mbox Inbox.mbox --output /tmp/emails.json
python3 scripts/build_report.py --input /tmp/emails.json --output /tmp/report
# Open /tmp/report.html in a browser

---

AI analysis templates#

After loading the email JSON into the AI context, use the following templates:

Part A: 4-Dimension Email Summary#

text

🔥 Part 1 — Important & Action Items
  🚨 [URGENT]    Subject — Sender — Date | Summary | Action | Deadline
  ⚡ [IMPORTANT] Subject — Sender — Date | Summary | Action
  📌 [NOTE]      Subject — Sender — Date | Summary

📊 Part 2 — Grouped by Sender / Topic

✅ Part 3 — To-Do List

📅 Part 4 — Timeline (YYYY-MM-DD  Sender → Subject: summary)

Part B: Contact Profile Analysis#

Sort by total interactions. For each contact:

text

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
👤 Rank #N | Name <email>   Total: N (Recv: N / Sent: N)
🧑 Gender       M/F/Unknown  Confidence: H/M/L  Basis: …
💼 Role         …            Basis: domain / signature / keywords
🔗 Relationship Colleague / Client / Institution / Stranger
   Direction    Mutual / Owner-initiated / Contact-initiated
📝 Topics       • subject 1  • subject 2
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Heat scale: 🔥 Heavy (≥10) · ⚡ Active (5–9) · 💬 Moderate (2–4) · 🌙 Light (1)

---

Notes#

• Credentials are passed via environment variables — never hardcoded
• IMAP connections use readonly mode — emails are never modified or deleted
• Body text is truncated to 2000 characters per email
• fetch_imap.py sends an RFC 2971 ID command required by 163/188 servers; harmless on others