从零跑通 SendmailSkills:手把手让 AI Agent 用 SMTP 自动发邮件
从零跑通 SendmailSkills:手把手让 AI Agent 用 SMTP 自动发邮件
项目地址:https://gitcode.com/agent-best-practices/SendmailSkills 本文是一篇上手教程:从拿授权码到发出第一封信,再到多账号路由、HTML 正文、附件与排错,全程可复制。 核心实现只用 Python 标准库(
smtplib+
读完这篇你能做到什么
按本文走一遍,你会完成这样一条链路:
拿到技能 → 申请邮箱授权码 → 写 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 | 开启两步验证 → 生成「应用专用密码」 |
两个必须记住的点:
- 授权码 ≠ 登录密码。 拿登录密码去填,会收到
SMTPAuthenticationError。 - 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 应当:
- 确认发件人(用配置里的哪个账号)
- 确认收件人、主题、正文
- 调用本技能执行发送
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 邮箱 | 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() 的执行顺序,改造它之前建议先读一遍:
- 参数校验:
to→subject→body依次判空,任一为空即返回错误(注意:空白字符串也算缺失) - 加载配置:读取
accounts.json;文件缺失或 JSON 坏 → 静默空列表 → 报错 - 解析账号:按
from_addr匹配,否则取第一个;再推断 host/port - 构造邮件:
MIMEMultipart;From: 名称 <邮箱>;To:;Subject:;cc 追加进头部与名单;bcc 只进名单 - 挂载正文:
MIMEText(body, "html" if is_html else "plain", "utf-8") - 挂载附件(可选):读文件为二进制,
MIMEApplication,文件名按 utf-8 编码 - 连接并发送:
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;文中中文头部编码结论为本地实测。
- 点赞
- 收藏
- 关注作者
评论(0)