从零跑通 SendmailSkills:手把手让 AI Agent 用 SMTP 自动发邮件

举报
yd_274732647 发表于 2026/10/28 16:08:09 2026/10/28
【摘要】 SendmailSkills 是一个纯 Python 标准库实现的 Agent 发邮件技能:配好邮箱授权码,就能让 AI 智能体自动撰写并发送邮件,支持 QQ/163/126/新浪/Gmail 多账号路由、HTML 正文、抄送密送与附件。本文是可复制的上手教程:从申请授权码、写 accounts.json、发出第一封信,到多账号路由机制、排错对照表与关键实现拆解,并实测验证中文主题编码。

从零跑通 SendmailSkills:手把手让 AI Agent 用 SMTP 自动发邮件

项目地址:https://gitcode.com/agent-best-practices/SendmailSkills 本文是一篇上手教程:从拿授权码到发出第一封信,再到多账号路由、HTML 正文、附件与排错,全程可复制。 核心实现只用 Python 标准库(smtplib + email),不需要 pip 安装任何东西。

读完这篇你能做到什么

按本文走一遍,你会完成这样一条链路:

拿到技能 → 申请邮箱授权码 → 写 accounts.json → 发出第一封信
→ 换用模块/对话方式调用 → HTML 正文/抄送密送/附件 → 多账号路由 → 排错

每一步都会先说明"它到底怎么工作",再给可复制命令——因为踩坑基本都出在"不知道它内部怎么选服务器/怎么校验参数"上。

前置条件清单

项 要求 怎么确认
Python 3.7 或更高 python3 --version
邮箱 QQ / 163 / 126 / 新浪 / Gmail 任一个 能登录网页版
授权码 不是登录密码 见第 2 步,各家申请方式不同
收件人 一个你能验证收信的邮箱 建议先用自己另一个邮箱试

⚠️ 先划边界:Outlook / 微软邮箱不支持(它要求 OAuth2,本项目走的是 SMTP 账号密码认证)。请用上面列出的邮箱。


第 1 步:拿到技能

克隆仓库:

git clone https://gitcode.com/agent-best-practices/SendmailSkills.git
cd SendmailSkills

目录结构很小,先认清各文件职责:

SendmailSkills/
├── SKILL.md                       # 技能定义(Agent 读它来决定怎么用)
├── README.md                      # 人看的使用说明
├── config/
│   ├── accounts.example.json      # 配置模板(要复制成 accounts.json)
│   └── accounts.json              # 你的真实配置(已 gitignore,不会提交)
└── scripts/
    └── send_mail.py               # 核心脚本,250 行,纯标准库

一句话理解这套设计:SKILL.md 给 Agent 看,README.md 给人看,send_mail.py 干活,accounts.json 放密钥。


第 2 步:申请邮箱授权码(这一步最容易卡住)

授权码是"给第三方客户端用的专用密码",和你平时登录网页的密码是两回事。

邮箱 SMTP 服务器 端口 申请路径
QQ 邮箱 smtp.qq.com 587 设置 → 账户 → 开启「POP3/SMTP 服务」→ 生成授权码
163 邮箱 smtp.163.com 465 设置 → POP3/SMTP/IMAP → 开启 SMTP → 生成授权码
126 邮箱 smtp.126.com 465 同 163
新浪邮箱 smtp.sina.com 465 设置 → 客户端 POP3/SMTP → 开启 → 获取授权码
Gmail smtp.gmail.com 587 开启两步验证 → 生成「应用专用密码」

两个必须记住的点:

  1. 授权码 ≠ 登录密码。 拿登录密码去填,会收到 SMTPAuthenticationError。
  2. QQ 邮箱生成授权码时会给你一串 16 位字符,只显示一次,当场复制存好。

第 3 步:写配置文件

复制模板:

cp config/accounts.example.json config/accounts.json

然后编辑 config/accounts.json,填账号和授权码:

{
  "accounts": [
    {
      "name": "我的QQ邮箱",
      "provider": "qq",
      "user": "yourname@qq.com",
      "auth_code": "你的QQ邮箱授权码",
      "from_name": "张三"
    },
    {
      "name": "我的163邮箱",
      "provider": "163",
      "user": "yourname@163.com",
      "auth_code": "你的163邮箱授权码",
      "from_name": "张三"
    }
  ]
}

字段含义与默认行为:

字段 必需 说明
provider 否 qq / 163 / 126 / sina / gmail / custom。填了就自动带出 host 和 port,不用手写
user 是 邮箱地址,同时作为 SMTP 登录用户名
auth_code 是 授权码 / 应用专用密码
from_name 否 收件人看到的发件人名称;留空则直接用邮箱地址
host / port custom 时必需 只在使用 custom 时需要自己提供

只配一个邮箱也完全没问题,accounts 数组里放一个对象即可。


第 4 步:发出第一封信(CLI 方式)

python3 scripts/send_mail.py \
  --config config/accounts.json \
  --from "yourname@qq.com" \
  --to "receiver@example.com" \
  --subject "会议通知" \
  --body "明天下午 3 点开会"

成功时会打印:

邮件已发送至 receiver@example.com

退出码为 0。失败时错误信息走 stderr、退出码为 1:

[错误] SMTP 认证失败:授权码错误。QQ/163/126/新浪邮箱请使用「授权码」(非登录密码),Gmail 请使用「应用专用密码」。

这个退出码约定很重要:在脚本/流水线里判断成败,看退出码,不要去 grep 输出文字。

--from 可以省略——不传就用配置文件里的第一个账号。


第 5 步:三种调用方式,按场景选

方式一:CLI(适合人手动跑、适合 crontab)

就是第 4 步的写法。完整参数:

python3 scripts/send_mail.py \
  --config config/accounts.json \
  --from yourname@qq.com \
  --to "a@example.com,b@example.com" \
  --subject "会议通知" \
  --body "明天下午 3 点开会" \
  [--html] \
  [--cc "cc@example.com"] \
  [--bcc "bcc@example.com"] \
  [--attachment "/path/to/file.pdf"]

--to / --cc / --bcc 都支持逗号或分号分隔,多个收件人一次投递。

方式二:作为 Python 模块(适合写进自己的程序)

from scripts.send_mail import send_email

result = send_email(
    config_path="config/accounts.json",
    from_addr="yourname@qq.com",      # 可选,不传则用第一个账号
    to="receiver@example.com",
    subject="会议通知",
    body="明天下午 3 点开会",
    is_html=False,
)
print(result)   # {'ok': True, 'message': '邮件已发送至 receiver@example.com'}

统一返回 dict,永不抛异常——成功是 {"ok": True, "message": ...},失败是 {"ok": False, "error": ...}。这一点对 Agent 很友好:它不需要 try/except,直接看 ok 字段。

方式三:Agent 对话式调用(这个技能的本意)

当用户在对话里说「帮我发邮件给 xxx」,Agent 应当:

  1. 确认发件人(用配置里的哪个账号)
  2. 确认收件人、主题、正文
  3. 调用本技能执行发送

SKILL.md 里明确写了这个三段式,还额外要求:发送前让 Agent 确认收件人、主题、正文无误,避免误发。 这是给"不可逆操作"留的安全闸。


第 6 步:进阶用法

HTML 正文

python3 scripts/send_mail.py --config config/accounts.json \
  --to "receiver@example.com" --subject "周报" \
  --body "<h2>本周进展</h2><ul><li>完成 A</li><li>完成 B</li></ul>" --html

加 --html 后 MIMEText 的 content-type 从 plain 变 html;模块方式对应 is_html=True。

抄送与密送

... --cc "boss@example.com" --bcc "archive@example.com"

内部处理有个细节值得知道:抄送(cc)会写进邮件头 Cc:,而密送(bcc)只加进投递名单、绝不写进邮件头——这正是密送应有的语义,bcc 收件人不会互相暴露。

附件

... --attachment "/path/to/报告.pdf"

附件走 MIMEApplication,文件名用 ("utf-8", "", att_path.name) 编码,所以中文文件名不会乱码。若路径不存在,直接返回错误而不发信:

附件不存在: /path/to/报告.pdf

第 7 步:多账号路由是怎么工作的

这是本项目最容易"用错了还不知道"的地方,值得单独讲。

你在配置里可以写多个账号,send_email 挑选逻辑是:

1. 如果传了 from_addr → 在 accounts 里找 user 完全等于它的那个
2. 找不到(或没传)→ 直接用 accounts[0](第一个账号)
3. 拿到账号后,推断 SMTP 服务器与端口

第 3 步的推断规则分三层,从最可靠到最兜底:

情况 行为
provider 是 qq/163/126/sina/gmail 查内置预设表,直接用官方 host/port
provider 是 custom 用你写的 host / port;缺任一个则直接报"无法解析发件人账号"
没写 provider 从邮箱域名猜:qq.com→qq、163.com→163、126.com→126、sina.com/sina.cn→sina、gmail.com→gmail
域名也猜不出来 兜底 smtp.<你的域名>:465

所以:填对 provider 最省事;用企业自建邮箱就写 provider: "custom" 并显式给出 host/port;别指望兜底规则对自建服务器一定正确(它只是猜 smtp.域名:465)。


第 8 步:排错对照表

先记住返回结构:失败一定是 {"ok": false, "error": "..."},CLI 模式下还会打到 stderr 并以退出码 1 结束。

现象 / 错误 原因 怎么办
SMTP 认证失败:授权码错误 用了登录密码,或授权码失效/过期 重新申请授权码;Gmail 用应用专用密码
无法连接 SMTP 服务器 host:port 网络不通、服务器地址错、端口被防火墙拦 换网络试;确认不是公司网络封了 465/587
缺少收件人(to) 没传收件人 补 --to
缺少邮件主题(subject) / 缺少邮件正文(body) 参数为空 补上;注意空字符串也算缺失
未找到配置文件 xxx,请先复制 accounts.example.json... 配置路径不对或 JSON 写坏了 见下方说明
账号 xxx 未配置授权码 auth_code 为空 补上授权码
附件不存在: xxx 附件路径错 用绝对路径重试
无法解析发件人账号,请检查配置文件 用了 custom 但没给 host/port 补 host 与 port

一个不易定位的坑:_load_accounts() 在"文件不存在"和"JSON 解析失败"两种情况下一律静默返回空列表,于是对外都表现为"未找到配置文件"。所以看到这个提示时,别只怀疑路径——也要检查 JSON 是不是有语法错(多一个逗号、用了中文引号都算):

python3 -c "import json;print('JSON OK:',len(json.load(open('config/accounts.json'))['accounts']),'个账号')"

第 9 步:安全与工程细节

密钥只放本地。 授权码写在 config/accounts.json,该文件已进 .gitignore,不会被提交。分享/备份仓库前自查一次:

git status --porcelain config/        # 期望:没有 accounts.json 出现在待提交列表
grep -rn "auth_code" config/*.json     # 确认没把真实授权码写进模板文件

发送前确认。 发邮件是不可逆操作,发出去就收不回。SKILL.md 特意要求 Agent 在发送前复述收件人/主题/正文一遍。自己写脚本调用时也建议:先 print 出将要发送的内容,确认后再真调用。

中文编码:不需要你操心。 很多人会担心"代码里 msg["Subject"] = subject 没有走 email.header.Header,中文主题会不会报错"。实测(Python 3):

from email.mime.multipart import MIMEMultipart
m = MIMEMultipart()
m["From"] = "张三 <a@qq.com>"
m["Subject"] = "会议通知"
print(m.as_string()[:80])
# From: =?utf-8?b?5byg5LiJ...?=   ← 自动做了 RFC2047 编码

序列化时头部会被自动编码为 =?utf-8?b?...?=,smtplib.sendmail() 也能正常发出。中文发件人名、中文主题都是开箱可用的。


附录 A:provider 速查表

provider 邮箱 host port 连接方式
qq QQ 邮箱 smtp.qq.com 587 STARTTLS(先明文握手再升级加密)
163 163 邮箱 smtp.163.com 465 隐式 SSL(全程加密)
126 126 邮箱 smtp.126.com 465 隐式 SSL
sina 新浪邮箱 smtp.sina.com 465 隐式 SSL
gmail Gmail smtp.gmail.com 587 STARTTLS
custom 自定义 自填 自填 看端口:465 走 SSL,其它走 STARTTLS

这张表的第 5 列不是装饰——项目就是按端口决定连接方式(见下一节),所以你自建/自定义服务器时,端口填 465 或其它值会走完全不同的握手流程。


附录 B:关键实现拆解(想改代码的看这里)

核心函数 send_email() 的执行顺序,改造它之前建议先读一遍:

  1. 参数校验:to → subject → body 依次判空,任一为空即返回错误(注意:空白字符串也算缺失)
  2. 加载配置:读取 accounts.json;文件缺失或 JSON 坏 → 静默空列表 → 报错
  3. 解析账号:按 from_addr 匹配,否则取第一个;再推断 host/port
  4. 构造邮件:MIMEMultipart;From: 名称 <邮箱>;To:;Subject:;cc 追加进头部与名单;bcc 只进名单
  5. 挂载正文:MIMEText(body, "html" if is_html else "plain", "utf-8")
  6. 挂载附件(可选):读文件为二进制,MIMEApplication,文件名按 utf-8 编码
  7. 连接并发送:
if smtp_port == 465:
    server = smtplib.SMTP_SSL(smtp_host, smtp_port, timeout=30)
else:
    server = smtplib.SMTP(smtp_host, smtp_port, timeout=30)
    server.ehlo(); server.starttls(); server.ehlo()
server.login(smtp_user, smtp_password)
server.sendmail(smtp_user, all_recipients, msg.as_string())

三个值得学的点:

  • 按端口选 SSL 方式:465 用 SMTP_SSL(隐式加密),其它端口用 SMTP + starttls()(显式升级)。这是 SMTP 最常见的坑,项目处理得对。
  • timeout=30:避免网络异常时脚本无限挂住——写自动化脚本时这个参数很关键。
  • 异常被收敛成返回值:SMTPAuthenticationError / SMTPConnectError 各自映射成人话提示,其余异常兜底为 发送失败: ...,一律 ok: False,绝不把 traceback 抛给上层。对 Agent 场景这是正确取舍。

常见问题(FAQ)

Q:我不想暴露真实授权码,能用环境变量吗? 配置里只支持写在 JSON。想更安全,可以在自己封装的入口把 auth_code 从环境变量注入后再调用 send_email(),但不要把注入后的文件落盘。

Q:能群发很多人吗? --to 支持逗号/分号分隔多个地址,但本项目是"一次 SMTP 投递给多个收件人",不做循环个性化群发。真要群发,请自己在外层循环调用,并注意服务商的风控频率限制。

Q:为什么 Outlook 不行? Outlook 已关闭基本身份验证,只支持 OAuth2,而本项目用的是 SMTP 用户名/授权码认证。换个邮箱即可。

Q:发出去没收到怎么办? 先看返回值——ok: true 只代表SMTP 服务器接受了投递,不代表对方一定进了收件箱。没收到先查对方垃圾箱,再确认发件域名的 SPF/DKIM 配置。

Q:能发给自己吗? 可以,--to 和 --from 填同一个地址,用来做链路自检。


结语

SendmailSkills 的价值不在于"把邮件发出去"这件事本身——smtplib 十几行就能做到——而在于它把发邮件做成了一个可被 Agent 安全调用的能力:

  • 统一返回 ok/error,不抛异常,Agent 不需要写 try/except
  • 授权码与代码分离、.gitignore 兜住密钥
  • 服务商差异被压进一张预设表,用户不用记 host/port
  • SKILL.md 里明确要求"发送前确认",给不可逆操作留了闸

现在你可以回到第 4 步,给自己发一封测试邮件,跑通整条链路。


参考资料:项目 README.md、SKILL.md、scripts/send_mail.py(250 行)、config/accounts.example.json;文中中文头部编码结论为本地实测。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。