yagmail,一个顺手的 Python 库

大家好，我是木木。

今天给大家分享一个顺手的 Python 库，yagmail。

yagmail

很多自动化脚本最后都绕不开“发一封邮件”：日报、告警、导出结果、任务完成通知。直接用 smtplib 能做，但 MIME、HTML、附件和收件人格式写起来容易啰嗦。yagmail 的定位很简单，就是把 Gmail/SMTP 发送邮件这件事封装得更顺手，让小脚本少写样板代码。

项目地址：https://github.com/kootenpv/yagmail

官方文档：https://yagmail.readthedocs.io/

三大特点

上手简单

用一个 SMTP 对象就能准备邮件内容，收件人、主题、正文和附件都比较直观。

内容灵活

正文可以混合普通文本和 HTML，也支持附件，适合报表、告警和自动化通知。

边界清楚

它负责客户端发送，不负责邮件平台治理；账号安全和授权方式仍要自己配置好。

最佳实践

安装方式：python -m pip install yagmail==0.15.293

功能一：配置 SMTP 对象

这段代码解决什么问题：先创建一个 SMTP 客户端对象，把账号、主机、端口和 TLS 方式集中配置。示例使用占位地址，不会真正连接邮件服务器。

importwarningswarnings.filterwarnings("ignore")importyagmailsmtp=yagmail.SMTP(user="sender@example.com",password="not-used",host="smtp.example.com",port=587,smtp_starttls=True,smtp_ssl=False,)print("user:",smtp.user)print("host:",smtp.host)print("port:",smtp.port)print("starttls:",smtp.smtp_starttls)

生产环境里不要把密码硬编码到脚本中。更稳的做法是放在本地凭证文件、密钥管理服务或 CI/CD 的安全变量里，并优先使用应用专用密码或 OAuth2。

功能二：先组装邮件，不立刻发送

这段代码解决什么问题：在真正发信前，先用 prepare_send 组装出 MIME 邮件内容，检查收件人、主题和内容类型。这样能降低线上脚本误发的概率。

importwarningswarnings.filterwarnings("ignore")fromemail.parserimportParserimportyagmailsmtp=yagmail.SMTP(user="sender@example.com",password="not-used",host="smtp.example.com",port=587,smtp_starttls=True,smtp_ssl=False,)recipients,raw_message=smtp.prepare_send(to=["reader@example.com"],subject="Daily report",contents=["Hi team,","<b>Report is ready.</b>"],)message=Parser().parsestr(raw_message)print("recipients:",", ".join(recipients))print("subject:",message["Subject"])print("from:",message["From"])print("content type:",message.get_content_type())

这个技巧适合写测试：你可以验证邮件主题、收件人、HTML 内容和附件是否正确，而不是每跑一次测试就真的发一封邮件。

环境与版本信息

• Demo 环境：Windows 11，Python 3.11
• 本文安装的 yagmail 版本：0.15.293
• 当前包未在 PyPI 元数据中声明 Requires-Python
• 关键依赖版本：premailer 3.10.0、cssutils 2.15.0、keyring 25.7.0
• 项目最近一次提交时间：2022-09-28T22:43:53+02:00

高级功能

这段代码解决什么问题：给邮件添加附件，并在发送前确认 MIME 结构里确实包含文件。对日报、导出结果、巡检报告这类任务很实用。

importwarningswarnings.filterwarnings("ignore")fromemail.parserimportParserfrompathlibimportPathfromtempfileimportTemporaryDirectoryimportyagmailsmtp=yagmail.SMTP(user="sender@example.com",password="not-used",host="smtp.example.com",port=587,smtp_starttls=True,smtp_ssl=False,)withTemporaryDirectory()astemp_dir:report=Path(temp_dir)/"report.txt"report.write_text("orders=18\nrevenue=3200",encoding="utf-8")recipients,raw_message=smtp.prepare_send(to="ops@example.com",subject="Ops summary",contents="The report is attached.",attachments=[str(report)],)message=Parser().parsestr(raw_message)print("to:",", ".join(recipients))print("content type:",message.get_content_type())print("has report:","report.txt"inraw_message)print("message bytes:",len(raw_message.encode("utf-8")))

附件发送看起来简单，但上线时要限制文件大小、文件类型和收件人范围。尤其是自动化脚本，最好先在测试邮箱里跑一轮。

适用场景

• 你要在脚本里发送日报、告警、任务完成通知或小型报表。
• 你想减少 smtplib 和 MIME 组装的样板代码。
• 你需要在测试中先组装邮件，再检查内容是否正确。

不适用场景

• 你需要大规模营销邮件、退信处理、投递统计和模板管理。
• 你所在团队要求统一邮件网关、审计和权限管控。
• 你不想自己处理账号授权、应用密码、SMTP 限流和安全策略。

上线检查

1. 使用应用专用密码、OAuth2 或安全凭证文件，不要把密码写进代码仓库。
2. 给发信脚本加收件人白名单、发送频率限制和失败重试日志。
3. 先用 prepare_send 或测试邮箱验证主题、正文和附件，再接入正式任务。

总结

yagmail 的优点是顺手：让 Python 脚本发邮件少写很多 MIME 和 SMTP 样板代码。它适合小型自动化通知和内部工具，但不替代专业邮件平台；账号安全、发送限流和审计仍然要认真处理。