Email Summarizer + Contact Profiler
Three independent stages — run any subset depending on what you need:
CODEBLOCK0
Each stage reads from / writes to files (or stdin/stdout), so they compose freely.
Installation
CODEBLOCK1
Script Reference
Stage 1 — Data Source
fetch_imap.py — Fetch emails from a live IMAP mailbox
CODEBLOCK2
| Flag | Default | Description |
|---|
| INLINECODE1 | 7 | Fetch last N days. Ignored if --since is set. |
| INLINECODE3 |
— | Start date inclusive (YYYY-MM-DD) |
|
--until DATE | — | End date exclusive (YYYY-MM-DD, default: today) |
|
--max N | 200 | Max emails per folder |
|
--folder NAME | INBOX | Inbox folder name |
|
--preset NAME | 163 | Mailbox preset:
163 \|
qq \|
exmail \|
gmail \|
outlook |
|
--with-sent | off | Also fetch Sent folder (recommended for relationship analysis) |
|
--output FILE | stdout | Write JSON to file; prints to stdout if omitted |
Supported presets:
| Preset | IMAP Server | Sent folder |
|---|
| INLINECODE15 | imap.163.com:993 | 已发送 |
| INLINECODE16 |
imap.qq.com:993 | Sent Messages |
|
exmail | imap.exmail.qq.com:993 | Sent Messages |
|
gmail | imap.gmail.com:993 | [Gmail]/Sent Mail |
|
outlook | outlook.office365.com:993 | Sent Items |
parse_file.py — Parse a local email export
CODEBLOCK3
| Flag | Default | Description |
|---|
| INLINECODE21 | — | Outlook .pst archive |
| INLINECODE22 |
— | Unix mbox file |
|
--msg-dir DIR | — | Folder of .msg files |
|
--sent-mbox FILE | — | Additional sent-items mbox (with
--mbox) |
|
--pst-engine | auto |
auto \|
native \|
readpst |
|
--days N | all | Only include last N days |
|
--since DATE | — | Start date inclusive (YYYY-MM-DD) |
|
--until DATE | — | End date exclusive (YYYY-MM-DD) |
|
--max N | 500 | Max emails to load |
|
--output FILE | stdout | Write JSON to file; prints to stdout if omitted |
PST engines:
| Engine | Flag | Requires |
|---|
| Native (default) | INLINECODE35 | INLINECODE36 |
| Readpst |
--pst-engine readpst |
apt install pst-utils or
brew install libpst |
| Auto |
--pst-engine auto | Tries native first, falls back to readpst |
Stage 2 — Analysis
build_report.py — Analyse emails → HTML + Excel report
CODEBLOCK4
| Flag | Default | Description |
|---|
| INLINECODE42 | stdin | Path to emails JSON from Stage 1 |
| INLINECODE43 |
contact_report | Output path prefix. Writes
<prefix>.html and
<prefix>.xlsx |
|
--owner EMAIL | auto-inferred | Mailbox owner address. Auto-detected if omitted. |
Output files:
- -
<prefix>.html — self-contained HTML report (open in browser or attach to email) - INLINECODE48 — 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
CODEBLOCK5
| Flag | Default | Description |
|---|
| INLINECODE58 | required | HTML file to use as email body |
| INLINECODE59 |
— | Excel file to attach (optional) |
|
--to ADDR | EMAIL_USER | Recipient address |
|
--subject STR | auto | Email subject (auto-generated if omitted) |
|
--preset NAME | 163 | SMTP preset:
163 \|
qq \|
exmail \|
gmail \|
outlook |
Private library modules (not standalone scripts)
| File | Provides |
|---|
| INLINECODE68 | INLINECODE69 , parse_addr, get_domain, strip_html, html_esc, INLINECODE74 |
| INLINECODE75 |
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
CODEBLOCK6
B — PST file → report → send to someone
CODEBLOCK7
C — One-liner (pipe, no intermediate files)
CODEBLOCK8
D — Report only, no email (open locally)
CODEBLOCK9
AI analysis templates
After loading the email JSON into the AI context, use the following templates:
Part A: 4-Dimension Email Summary
CODEBLOCK10
Part B: Contact Profile Analysis
Sort by total interactions. For each contact:
CODEBLOCK11
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
- INLINECODE82 sends an RFC 2971 ID command required by 163/188 servers; harmless on others
邮件摘要生成器 + 联系人画像工具
三个独立阶段 — 根据需求运行任意子集：
[数据源] [分析] [投递]
fetch_imap.py ──→ ──→
parsefile.py ──→ buildreport.py ──→ send_report.py
→ .html + .xlsx
每个阶段从文件读取/写入文件（或标准输入/输出），因此可自由组合。
安装
bash
Python 依赖
pip install -r requirements.txt
Node.js 依赖（仅用于原生 .pst 解析）
cd scripts && npm install && cd ..
脚本参考
阶段 1 — 数据源
fetch_imap.py — 从实时 IMAP 邮箱获取邮件
bash
export EMAIL_USER=you@163.com
export EMAIL_PASS=your-app-password
获取最近 7 天（仅收件箱）→ emails.json
python3 scripts/fetch_imap.py --days 7 --output emails.json
获取日期范围，收件箱 + 已发送
python3 scripts/fetch_imap.py --since 2026-03-01 --until 2026-03-28 \
--with-sent --preset 163 --output emails.json
直接管道传输到 build_report.py（无需中间文件）
python3 scripts/fetch
imap.py --days 30 | python3 scripts/buildreport.py --output report
| 参数 | 默认值 | 描述 |
|---|
| --days N | 7 | 获取最近 N 天。如果设置了 --since 则忽略。 |
| --since DATE |
— | 开始日期（包含，YYYY-MM-DD） |
| --until DATE | — | 结束日期（不包含，YYYY-MM-DD，默认：今天） |
| --max N | 200 | 每个文件夹最大邮件数 |
| --folder NAME | INBOX | 收件箱文件夹名称 |
| --preset NAME | 163 | 邮箱预设：163 \| qq \| exmail \| gmail \| outlook |
| --with-sent | 关闭 | 同时获取已发送文件夹（建议用于关系分析） |
| --output FILE | stdout | 将 JSON 写入文件；省略则输出到标准输出 |
支持的预设：
| 预设 | IMAP 服务器 | 已发送文件夹 |
|---|
| 163 | imap.163.com:993 | 已发送 |
| qq |
imap.qq.com:993 | Sent Messages |
| exmail | imap.exmail.qq.com:993 | Sent Messages |
| gmail | imap.gmail.com:993 | [Gmail]/Sent Mail |
| outlook | outlook.office365.com:993 | Sent Items |
parse_file.py — 解析本地邮件导出文件
bash
解析 .pst 文件（原生引擎，无需系统安装）
python3 scripts/parse_file.py --pst ~/Downloads/archive.pst --output emails.json
解析 .mbox 文件（收件箱 + 已发送）
python3 scripts/parse_file.py --mbox Inbox.mbox --sent-mbox Sent.mbox --output emails.json
解析 .msg 文件文件夹，按日期过滤
python3 scripts/parse_file.py --msg-dir ./exported/ --since 2026-01-01 --output emails.json
管道传输到 build_report.py
python3 scripts/parse
file.py --pst archive.pst | python3 scripts/buildreport.py --output report
| 参数 | 默认值 | 描述 |
|---|
| --pst FILE | — | Outlook .pst 存档 |
| --mbox FILE |
— | Unix mbox 文件 |
| --msg-dir DIR | — | .msg 文件文件夹 |
| --sent-mbox FILE | — | 额外的已发送邮件 mbox（与 --mbox 一起使用） |
| --pst-engine | auto | auto \| native \| readpst |
| --days N | all | 仅包含最近 N 天 |
| --since DATE | — | 开始日期（包含，YYYY-MM-DD） |
| --until DATE | — | 结束日期（不包含，YYYY-MM-DD） |
| --max N | 500 | 最大加载邮件数 |
| --output FILE | stdout | 将 JSON 写入文件；省略则输出到标准输出 |
PST 引擎：
| 引擎 | 参数 | 要求 |
|---|
| 原生（默认） | --pst-engine native | cd scripts && npm install |
| Readpst |
--pst-engine readpst | apt install pst-utils 或 brew install libpst |
| 自动 | --pst-engine auto | 优先尝试原生引擎，失败则回退到 readpst |
阶段 2 — 分析
build_report.py — 分析邮件 → HTML + Excel 报告
bash
从文件
python3 scripts/build_report.py --input emails.json --output report
明确指定所有者（分析他人 PST 时）
python3 scripts/build_report.py --input emails.json --output report \
--owner xiang-xiang.hu@connect.polyu.hk
从标准输入（从阶段 1 管道传输）
python3 scripts/fetch
imap.py --days 30 | python3 scripts/buildreport.py --output report
| 参数 | 默认值 | 描述 |
|---|
| --input FILE | stdin | 阶段 1 输出的邮件 JSON 路径 |
| --output PREFIX |
contact_report | 输出路径前缀。生成
.html 和 .xlsx |
| --owner EMAIL | 自动推断 | 邮箱所有者地址。省略时自动检测。 |
输出文件：
- - .html — 自包含 HTML 报告（在浏览器中打开或附加到邮件）
- .xlsx — 包含相同数据的 Excel 电子表格
报告列：# / 首选名称 / 邮箱 / 公司 / 职位 / 主题摘要 / 来源 / 邮件数（收/发）
阶段 3 — 投递
send_report.py — 通过 SMTP 发送报告文件
bash
export EMAIL_USER=you@163.com
export EMAIL_PASS=your-app-password
向收件人发送 HTML + Excel
python3 scripts/send_report.py \
--html report.html --xlsx report.xlsx --to friend@example.com
发送给自己（EMAIL_USER）
python3 scripts/send_report.py --html report.html --xlsx report.xlsx
仅 HTML（无附件）
python3 scripts/send_report.py --html report.html --to friend@example.com
自定义主题
python3 scripts/send_report.py --html report.html --subject 三月联系人报告
| 参数 | 默认值 | 描述 |
|---|
| --html FILE | 必需 | 用作邮件正文的 HTML 文件 |
| --xlsx FILE |
— | 要附加的 Excel 文件（可选） |
| --to ADDR | EMAIL_USER | 收件人地址 |
| --subject STR | 自动 | 邮件主题（省略时自动生成） |
| --preset NAME | 163 | SMTP 预设：163 \| qq \| exmail \| gmail \| outlook |
私有库模块（非独立脚本）
| 文件 | 提供功能 |
|---|
| core.py | decodeheader、parseaddr、getdomain、striphtml、htmlesc、getbody |
| analyze.py |
inferowner、buildcontacts、域名/公司/职位/名称推断 |
| render.py | buildreporthtml、buildexcel、SMTP_MAP |
完整工作流示例
A — IMAP 邮箱 → 报告 → 发送给自己
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
