z-mail-reader

z-mail-reader — IMAP email reading and real-time monitoring

Overview

Connect to any mailbox via the IMAP protocol (defaults to QQ Mail), read emails within a specified time range, automatically download attachments and inline images locally, and generate email content summaries. Supports real-time polling monitoring, automatically processing new incoming emails and sending system notifications.

Core principle: Python imaplib → IMAP server → parse email → save attachments/images → Agent generates summary

Prerequisite configuration

Before use, set environment variables (or pass them in as parameters when calling):

export MAIL_IMAP_SERVER="imap.qq.com"    # IMAP 服务器地址
export MAIL_ADDR="your_email@qq.com"     # 邮箱地址
export MAIL_AUTH_CODE="your_auth_code"   # IMAP 授权码（非登录密码）

How to get a QQ Mail authorization code: QQ Mail → Settings → Account → POP3/IMAP/SMTP service → Enable IMAP → Generate authorization code

Storage directory

Email attachments, images, and summaries are saved to:

{output_dir}/
└── YYYYMMDD_HHMM_邮件主题/
    ├── 附件文件...
    ├── images/           # 正文中的图片
    │   ├── img_001.png
    │   └── ...
    └── sum.md            # 邮件摘要（Agent 生成）

Core workflow

1. 确定时间范围（本周/最近N天/自定义）
   ↓
2. 运行 Python 脚本连接 IMAP 获取邮件
   ↓
3. 脚本自动：解析邮件头、提取正文、下载附件、保存正文图片
   ↓
4. 为每封邮件创建独立目录（按时间+主题命名）
   ↓
5. Agent 阅读邮件内容，生成 sum.md 摘要
   ↓
6. 汇总输出邮件列表给用户

Script location

scripts/
├── read_emails.py      # IMAP 邮件读取
└── listen_emails.py    # 实时轮询监听

Usage

Read emails

python3 scripts/read_emails.py --email "you@qq.com" --auth-code "YOUR_CODE" --days 7

Parameter description

Parameter	Default value	Description
`--email`	Environment variable `MAIL_ADDR`	Email address
`--auth-code`	Environment variable `MAIL_AUTH_CODE`	IMAP authorization code
`--days`	7	Read the last N days
`--since`	-	Start date YYYY-MM-DD
`--until`	-	End date YYYY-MM-DD
`--folder`	INBOX	Mail folder
`--output-dir`	./mails	Output directory
`--limit`	100	Maximum number of emails
`--body-length`	3000	Body truncation length

Real-time monitoring

# 前台监听（Ctrl+C 停止）
python3 scripts/listen_emails.py --start

# 后台监听
python3 scripts/listen_emails.py --start > /dev/null 2>&1 &

# 查看状态
python3 scripts/listen_emails.py --status

# 停止
python3 scripts/listen_emails.py --stop

# 测试一次
python3 scripts/listen_emails.py --once

Output format

The script outputs JSON to stdout (progress information is output to stderr):

{
  "total": 5,
  "emails": [
    {
      "subject": "邮件主题",
      "from": "发件人",
      "date": "2026-06-05 14:30:00",
      "body_preview": "正文前3000字...",
      "attachments": [{"filename": "附件.pdf", "path": "...", "size": 12345}],
      "inline_images": [{"filename": "img_001.png", "path": "...", "size": 67890, "source": "cid"}],
      "output_dir": "/path/to/mails/20260605_1430_邮件主题",
      "has_attachments": true,
      "has_images": true
    }
  ]
}

Image saving instructions

The script automatically saves three types of body images:

Type	source	Description
CID inline images	`cid`	Images referenced by Content-ID in the email MIME
HTML external link images	`url`	`<img src="https://...">` Automatically downloaded
Base64 embedded images	`base64`	`data:image/...` encoded images

Agent workflow steps

1. Run the script to get emails

python3 scripts/read_emails.py --days 7

2. Generate sum.md for each email

In each email's output_dir create sum.md, containing: email metadata, summary, attachment list, body image references.

3. Summary report

Output a concise email list to the user.

Dependencies

Python 3.8+
imapclient(required for monitoring mode):pip3 install imapclient

Notes

Authorization code security: Environment variables are recommended; do not display the full authorization code in output
Attachment size: Oversized attachments (>50MB) may be skipped by the IMAP server
Encoding compatibility: The script automatically handles UTF-8/GBK/GB2312 encoding
IMAP limitations: Some mailboxes have rate limits; the default monitoring polling interval is 30 seconds
QQ Mail particularity: QQ Mail's IMAP IDLE does not push events; the script has built-in polling as a fallback

FAQ

Issue	Solution
Login failed	Check whether the authorization code is correct and whether IMAP is enabled for the mailbox
Emails not found	Try expanding the time range or checking the folder name
Attachment download failed	It may be an oversized attachment; check the network connection
Garbled message body	The script automatically handles common encodings
No response when listening	QQ Mail does not support IDLE push; a 30-second polling fallback is used