Z Mail Reader

Community

tjxj

z-mail-reader

Use when user wants to read emails, check inbox, fetch emails via IMAP, download email attachments, extract inline images, or summarize email content. Also supports real-time polling for new emails with system notifications. Triggers include read emails, check inbox, fetch emails, email summary, email attachments, mail listener, IMAP, QQ邮箱, Foxmail, 读邮件, 查看邮件, 收件箱, 邮件摘要, 邮件总结, 查收邮件, and 监听邮件.

Overview

Publisher	tjxj
Repository	`z-skills`
Skill name	`z-mail-reader`
Stars	548
Forks	102
Bundled files	2
Links	Skill source Repository

Markdown instructions
A SKILL.md file the model loads on demand, so it only costs tokens when a request actually matches.
Works with any LLM
AI skills are plain Markdown, not provider-specific code, so this works with GPT, Claude, Gemini, Grok, or a local model.
2 bundled files
Scripts, templates, and references the model can read while it works. Files are read-only and never executed.
Open source
Published by tjxj on GitHub. Read the source before you install it.

Installation

Install the Z Mail Reader AI skill in TypingMind to use it with any LLM, or drop it into another agent that reads SKILL.md.

Install in TypingMind

TypingMind installs a skill straight from its GitHub folder — it reads SKILL.md, bundles the resource files, and stores the result locally.

Open the app and go to Plugins → Skills.
Choose "Install from GitHub".
Paste the skill folder URL below and confirm.
https://github.com/tjxj/z-skills/tree/main/z-mail-reader
Enable the skill in any chat where you want it available.

Plugins → Skills → Add skill → From GitHub URL, then paste the folder URL and press Continue.

Install in another agent

Any agent that reads the Agent Skills format can use this skill — copy the folder into that agent's skills directory.

Claude Code — .claude/skills

git clone --depth 1 https://github.com/tjxj/z-skills.git /tmp/z-skills
mkdir -p .claude/skills
cp -r /tmp/z-skills/z-mail-reader .claude/skills/z-mail-reader

Restart Claude Code after copying so it picks up the new skill.

Use it in TypingMind

Enable Z Mail Reader in any TypingMind chat and the model takes it from there. Its name and description sit in the system prompt, and the moment a request matches, the model loads the full instructions itself — you never invoke it by hand, and it costs no tokens until it is actually used.

The model loads Z Mail Reader on its own as soon as a request matches it.

Works with any AI model

AI skills are plain Markdown instructions rather than provider-specific code, so Z Mail Reader is not tied to the model it was written for. Install it once in TypingMind and use it with GPT-5, Claude, Gemini, Grok, DeepSeek, Mistral, Llama, or a local model you run yourself — all on your own API keys.

Loaded only when it is needed
The system prompt carries just the name and description. The instructions are fetched on the first matching request, so an idle skill costs nothing.
Switch models mid-chat
Because the skill is instructions rather than code, changing model does not break it — the next model reads the same SKILL.md.

Skill instructions

This is the SKILL.md content the model loads. Read it before installing — a skill is instructions your model will follow.

z-mail-reader — IMAP 邮件读取与实时监听

Overview

通过 IMAP 协议连接任意邮箱（默认 QQ 邮箱），读取指定时间范围内的邮件，自动下载附件和内嵌图片到本地，并生成邮件内容摘要。支持 实时轮询监听，新邮件到达时自动处理并发送系统通知。

核心原理： Python imaplib → IMAP 服务器 → 解析邮件 → 保存附件/图片 → Agent 生成摘要

前置配置

使用前需设置环境变量（或在调用时通过参数传入）：

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

QQ 邮箱获取授权码方法： QQ邮箱 → 设置 → 账户 → POP3/IMAP/SMTP服务 → 开启 IMAP → 生成授权码

存储目录

邮件附件、图片和摘要保存到：


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

核心流程


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

脚本位置


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

使用方法

读取邮件

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

参数说明

参数	默认值	说明
`--email`	环境变量 `MAIL_ADDR`	邮箱地址
`--auth-code`	环境变量 `MAIL_AUTH_CODE`	IMAP 授权码
`--days`	7	读取最近 N 天
`--since`	-	起始日期 YYYY-MM-DD
`--until`	-	截止日期 YYYY-MM-DD
`--folder`	INBOX	邮件文件夹
`--output-dir`	./mails	输出目录
`--limit`	100	最大邮件数量
`--body-length`	3000	正文截取长度

实时监听

bash
# 前台监听（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

输出格式

脚本输出 JSON 到 stdout（进度信息输出到 stderr）：

json
{
  "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
    }
  ]
}

图片保存说明

脚本自动保存三类正文图片：

类型	source	说明
CID 内联图片	`cid`	邮件 MIME 中 Content-ID 引用的图片
HTML 外链图片	`url`	`<img src="https://...">` 自动下载
Base64 嵌入图	`base64`	`data:image/...` 编码的图片

Agent 工作步骤

1. 运行脚本获取邮件

bash
python3 scripts/read_emails.py --days 7

2. 为每封邮件生成 sum.md

在每封邮件的 output_dir 下创建 sum.md，包含：邮件元信息、摘要、附件列表、正文图片引用。

3. 汇总报告

向用户输出简洁的邮件列表。

依赖

Python 3.8+
imapclient（监听模式需要）：pip3 install imapclient

注意事项

授权码安全：推荐用环境变量，不要在输出中显示完整授权码
附件大小：超大附件（>50MB）可能被 IMAP 服务器跳过
编码兼容：脚本自动处理 UTF-8/GBK/GB2312 编码
IMAP 限制：部分邮箱有频率限制，监听轮询间隔默认30秒
QQ邮箱特殊性：QQ邮箱的 IMAP IDLE 不推送事件，脚本已内置轮询兜底

常见问题

问题	解决方案
登录失败	检查授权码是否正确，邮箱是否开启了 IMAP
找不到邮件	尝试扩大时间范围或检查文件夹名称
附件下载失败	可能是超大附件，检查网络连接
正文乱码	脚本已自动处理常见编码
监听无反应	QQ邮箱不支持 IDLE 推送，已用30秒轮询兜底

Bundled files

The model reads these on demand while the skill is loaded. They are exposed as readable files and are never executed.

scripts/listen_emails.py11 KB
scripts/read_emails.py20 KB

Frequently asked questions

What does the Z Mail Reader AI skill do?

Why use Z Mail Reader on TypingMind?

Because you install it once and use it with any model. Z Mail Reader is plain Markdown rather than provider-specific code, so the same skill runs on GPT-5, Claude, Gemini, Grok, or a local model — and you can switch model mid-chat without it breaking. TypingMind runs on your own API keys, so you pay providers directly instead of a per-seat subscription, and your skills and chats stay in your own storage.

How do I install Z Mail Reader in TypingMind?

Open Plugins → Skills → Install from GitHub in TypingMind and paste https://github.com/tjxj/z-skills/tree/main/z-mail-reader. TypingMind reads its SKILL.md and bundles its files and installs it as a skill you can enable per chat.

Which AI models can use Z Mail Reader?

Any model you connect in TypingMind. AI skills are plain Markdown instructions rather than provider-specific code, so GPT, Claude, Gemini, Grok, and local models can all load this skill when a request matches it.

How many AI models can I use with Z Mail Reader?

As many as you like. As long as a model supports skills, you can use Z Mail Reader with it — GPT, Claude, Gemini, Grok, DeepSeek, Mistral, Llama and more — all on TypingMind with your own API keys.

Is the Z Mail Reader AI skill free?

It is published on GitHub by tjxj. Check the repository for licensing terms. You only pay your own AI provider for the tokens you use.

What are AI skills?

An AI skill is a reusable instruction bundle that teaches an AI model how to do one specific task. It follows the open Agent Skills format: a SKILL.md file with a name and description, plus any scripts, templates or reference files the model may need. The model reads the instructions only when your request matches the skill, so an installed skill costs nothing until it is used.

How are AI skills different from plugins or MCP servers?

A plugin or MCP server gives a model new tools to call — code that runs somewhere and returns a result. An AI skill gives the model knowledge and process instead: how to approach a task, which steps to follow, what good output looks like. Skills are plain Markdown, so they need no server, no API key and no runtime, and they work with any model.

View all

Discord E2e

openclaw

OrganizationPopular

Test Discord with Convex-leased QA bots: check credentials without a Gateway, exercise owned messages, or prove OpenClaw replies, files, threads, reactions, streaming, and typing. Distinguish API and…

Openclaw Live Updater

openclaw

OrganizationPopular

Maintain the canonical live OpenClaw main checkout, macOS LaunchAgent-managed Gateway, local macOS app, exact-head main CI, and recurring full release validation. Use for fast-forward update…

Parallels Discord Roundtrip

openclaw

OrganizationPopular

Run macOS Parallels smoke with Discord send, host verification, host reply, and guest readback proof.

Configure Channel

Configure and prove a chat channel with non-interactive one-liners; secrets only as SecretRefs.

Overview

Installation

Install in TypingMind

Install in another agent

Use it in TypingMind

Works with any AI model

Skill instructions

z-mail-reader — IMAP 邮件读取与实时监听

Overview

前置配置

存储目录

核心流程

脚本位置

使用方法

读取邮件

参数说明

实时监听

输出格式

图片保存说明

Agent 工作步骤

1. 运行脚本获取邮件

2. 为每封邮件生成 sum.md

3. 汇总报告

依赖

注意事项

常见问题

Bundled files

Frequently asked questions

Related AI Skills

Set up your own AI workspace now