Email Master — 全功能邮件管理技能

概述

本技能使用 Python 标准库（smtplib + imaplib）实现完整的邮件收发管理，无需安装第三方依赖。

支持功能：

• 发送：纯文本/HTML正文（支持HTML文件路径）、多附件、内嵌图片、多收件人、抄送/密送、回复/转发邮件、高优先级
• 接收：列出邮件列表、分页浏览、仅看未读
• 搜索：按主题/发件人/收件人/日期/是否未读筛选
• 查看：完整邮件内容（含正文、HTML、附件列表）、回复链信息、附件大小
• 管理：删除（支持批量）、标记已读/未读/星标（支持批量）、移动文件夹
• 下载：保存单个附件或全部附件到本地
• 自动识别：根据邮箱地址自动匹配SMTP/IMAP配置

脚本说明

| 脚本 | 功能 |

|------|------|

| scripts/send_email.py | 邮件发送（SMTP，支持HTML+附件+回复/转发+重试）|

| scripts/mail_client.py | 邮件接收与管理（IMAP，兼容163 Unsafe Login）|

| scripts/email_config.py | 邮箱配置自动识别（根据邮箱地址匹配服务器配置）|

Python 运行路径（优先使用）：

C:\Users\admin\.workbuddy\binaries\python\versions\3.13.12\python.exe

快速开始

第一步：自动识别邮箱配置

python scripts/email_config.py user@163.com
# 自动输出：SMTP服务器、IMAP服务器、端口、认证方式

第二步：确认授权码

大多数邮箱不支持账户密码，需生成授权码/应用密码：

• 163/126：网页版 → 设置 → POP3/SMTP/IMAP → 开启 → 获取授权码
• QQ：邮箱设置 → 账户 → 生成授权码
• Gmail：Google账号 → 安全 → 两步验证 → 应用密码

第三步：发送或收取邮件

见下方详细用法。

邮箱配置参考

常用快查表（完整配置见 references/email_providers.md，也可用 email_config.py 自动查询）：

| 邮箱 | SMTP | IMAP | SSL端口 | 认证方式 |

|------|------|------|---------|---------|

| 163 | smtp.163.com | imap.163.com | 465/993 | 授权码 |

| QQ | smtp.qq.com | imap.qq.com | 465/993 | 授权码 |

| 126 | smtp.126.com | imap.126.com | 465/993 | 授权码 |

| Gmail | smtp.gmail.com | imap.gmail.com | 587/993 | 应用密码 |

| Outlook | smtp-mail.outlook.com | imap-mail.outlook.com | 587/993 | 应用密码 |

| Yahoo | smtp.mail.yahoo.com | imap.mail.yahoo.com | 465/993 | 应用密码 |

| iCloud | smtp.mail.me.com | imap.mail.me.com | 587/993 | 应用密码 |

| Aliyun | smtp.aliyun.com | imap.aliyun.com | 465/993 | 授权码 |

| 139 | smtp.139.com | imap.139.com | 465/993 | 授权码 |

| 189 | smtp.189.cn | imap.189.cn | 465/993 | 授权码 |

发送邮件

基本发送（纯文本）

python scripts/send_email.py \
  --host smtp.163.com --port 465 \
  --user tnktechqa@163.com --password "授权码" \
  --to "收件人@example.com" \
  --subject "邮件主题" \
  --body "邮件正文内容"

发送 HTML 邮件

# 直接传入HTML字符串
python scripts/send_email.py \
  --host smtp.163.com --port 465 \
  --user tnktechqa@163.com --password "授权码" \
  --to "收件人@example.com" \
  --subject "HTML邮件" \
  --html "<h1>你好</h1><p>这是一封 <b>HTML</b> 邮件。</p>"

# 传入HTML文件路径（自动读取文件内容）
python scripts/send_email.py \
  --host smtp.163.com --port 465 \
  --user tnktechqa@163.com --password "授权码" \
  --to "收件人@example.com" \
  --subject "月报" \
  --html "/path/to/report.html"

发送带附件的邮件

python scripts/send_email.py \
  --host smtp.163.com --port 465 \
  --user tnktechqa@163.com --password "授权码" \
  --to "收件人@example.com" \
  --subject "请查收报告" \
  --html "<p>请查收附件中的报告。</p>" \
  --attach "/path/to/report.pdf" "/path/to/data.xlsx"

发送给多人并抄送

python scripts/send_email.py \
  --host smtp.163.com --port 465 \
  --user tnktechqa@163.com --password "授权码" \
  --to "a@example.com,b@example.com" \
  --cc "boss@company.com" \
  --subject "通知" \
  --html "<p>内容</p>" \
  --from-name "技术团队"

回复邮件

# 传入原始邮件的 Message-ID（查看邮件详情时获取）
python scripts/send_email.py \
  --host smtp.163.com --port 465 \
  --user tnktechqa@163.com --password "授权码" \
  --to "sender@example.com" \
  --subject "Re: 原始主题" \
  --body "收到，谢谢！" \
  --reply-to "<msgid@example.com>"

高优先级邮件

python scripts/send_email.py \
  --host smtp.163.com --port 465 \
  --user tnktechqa@163.com --password "授权码" \
  --to "boss@company.com" \
  --subject "紧急通知" \
  --html "<p>紧急事项</p>" \
  --priority high

作为模块调用

import sys
sys.path.insert(0, "C:/Users/admin/.workbuddy/skills/email-master/scripts")
from send_email import send_email

result = send_email(
    host="smtp.163.com",
    port=465,
    user="tnktechqa@163.com",
    password="授权码",
    to=["收件人@example.com"],
    subject="主题",
    html_body="<h1>HTML内容</h1><p>正文</p>",
    attachments=["/path/to/file.pdf"],
    from_name="发件人名称",
    reply_to_msgid="<original-msg-id@example.com>",
    priority="high",
    max_retries=2,
)
print(result)  # {"success": True, "message": "..."}

接收与管理邮件

> 163/126/Yeah 邮箱注意：首次使用 IMAP 可能触发「Unsafe Login」安全限制。

> 本脚本已内置 ID 命令绕过机制。若仍被拒绝，请登录网页版邮箱确认授权。

> 详见下方「常见问题」。

列出文件夹

python scripts/mail_client.py \
  --host imap.163.com --user tnktechqa@163.com --password "授权码" \
  folders

列出收件箱最新20封

python scripts/mail_client.py \
  --host imap.163.com --user tnktechqa@163.com --password "授权码" \
  list --limit 20

只看未读邮件

python scripts/mail_client.py ... list --unread

搜索邮件

# 按主题搜索
python scripts/mail_client.py ... search --subject "发票"

# 按发件人搜索
python scripts/mail_client.py ... search --from "hr@company.com"

# 按日期范围搜索（格式：DD-Mon-YYYY，如 01-May-2024）
python scripts/mail_client.py ... search --since "01-May-2024" --before "31-May-2024"

# 组合搜索
python scripts/mail_client.py ... search --subject "合同" --from "legal@firm.com" --unread

查看邮件详情

# 查看并自动标记已读
python scripts/mail_client.py ... view --uid 123

# 查看但不标记已读
python scripts/mail_client.py ... view --uid 123 --no-mark-read

删除邮件（支持批量）

# 删除单封
python scripts/mail_client.py ... delete --uid 123

# 批量删除
python scripts/mail_client.py ... delete --uid "123,456,789"

标记邮件状态（支持批量）

# 标记为已读
python scripts/mail_client.py ... mark --uid 123 --flag read

# 批量标记未读
python scripts/mail_client.py ... mark --uid "123,456" --flag unread

# 添加星标
python scripts/mail_client.py ... mark --uid 123 --flag flagged

移动邮件到文件夹

python scripts/mail_client.py ... move --uid 123 --dest "已处理"

下载附件

# 下载指定附件
python scripts/mail_client.py ... download --uid 123 --filename "report.pdf" --dir "/path/to/save"

# 下载全部附件
python scripts/mail_client.py ... download --uid 123 --dir "/path/to/save"

获取邮箱统计

python scripts/mail_client.py ... stats

JSON格式输出（便于程序处理）

python scripts/mail_client.py ... list --json
python scripts/mail_client.py ... view --uid 123 --json

作为模块调用

import sys
sys.path.insert(0, "C:/Users/admin/.workbuddy/skills/email-master/scripts")
from mail_client import MailClient

with MailClient("imap.163.com", 993, "tnktechqa@163.com", "授权码") as client:
    # 列出邮件
    emails = client.list_emails(limit=10)
    for e in emails:
        print(e["subject"], e["from"], e["date"])

    # 搜索
    results = client.search_emails(subject="发票", unread_only=True)

    # 查看详情
    mail = client.get_email("123", mark_read=False)
    print(mail["subject"], mail["message_id"])

    # 批量删除
    client.delete_email("123,456,789")

    # 下载全部附件
    saved = client.download_all_attachments("123", save_dir="./downloads")

邮箱配置自动识别

# 查询邮箱配置
python scripts/email_config.py user@163.com
python scripts/email_config.py someone@gmail.com --json

# 作为模块调用
from email_config import get_email_config
config = get_email_config("user@163.com")
print(config["smtp_host"], config["smtp_port"])
print(config["imap_host"], config["imap_port"])
print(config["auth_guide"])

支持的邮箱域名：163.com、126.com、yeah.net、qq.com、sina.com、sohu.com、aliyun.com、139.com、189.cn、21cn.com、gmail.com、outlook.com、hotmail.com、live.com、yahoo.com、icloud.com、me.com、zoho.com、fastmail.com、protonmail.com 等 30+ 域名。

常见问题处理

| 错误 | 原因 | 解决方案 |

|------|------|---------|

| Authentication failed | 使用了账户密码而非授权码 | 在邮箱设置中生成授权码/应用密码 |

| Connection refused | 端口错误或服务未开启 | 检查端口，163/QQ需在网页端开启SMTP/IMAP |

| SSL error | 端口与加密方式不匹配 | 465用SSL，587用STARTTLS |

| 163 Unsafe Login | 网易邮箱安全保护 | 登录163网页版 → 设置 → POP3/SMTP/IMAP → 确认授权/开启IMAP；本脚本已内置ID命令绕过机制 |

| 163发送失败 | 未开启SMTP服务 | 登录163网页 → 设置 → POP3/SMTP/IMAP → 开启 |

| Gmail认证失败 | 未使用应用密码 | Google账号 → 安全 → 两步验证 → 应用密码 |

| SMTPServerDisconnected | 网络不稳定 | 已内置重试机制（默认2次），可 --retries 3 增加重试 |

| IMAP select失败 | 文件夹名错误 | 先用 folders 命令查看可用文件夹名 |

163邮箱「Unsafe Login」详细解决步骤

1. 登录 https://mail.163.com
2. 点击右上角「设置」→「POP3/SMTP/IMAP」
3. 确认 IMAP 服务已开启（如果未开启，点击开启并获取授权码）
4. 如果有「安全登录」提示弹窗，点击确认授权
5. 本脚本已内置 ID 命令自动发送客户端标识，可绕过大部分 Unsafe Login 检测
6. 如仍然失败，可能需要在网页版中先手动收取/发送一封邮件激活账户

参考资料

• 完整服务器配置表：references/email_providers.md
• 邮箱自动识别：scripts/email_config.py <邮箱地址>
• 发送脚本详细参数：scripts/send_email.py --help
• 接收脚本详细参数：scripts/mail_client.py --help