SMTP连接失败主因是邮箱未开SMTP服务、用登录密码而非授权码、端口错误或云服务器封禁端口；jinja2渲染需设MIMEText subtype="html"并用{{content|safe}}；附件中文名须用add_header keyword参数；防垃圾邮件须配SPF/DKIM、统一域名、避免免费邮箱发信。
SMTP 连接失败：认证被拒或超时
绝大多数邮件发送卡在第一步，不是代码写错，而是 SMTP 服务端拒绝连接。常见现象是 SMTPAuthenticationError、TimeoutError 或 ConnectionRefusedError。
根本原因往往不是 Python 代码问题，而是：
- 邮箱未开启 SMTP 服务（如 QQ 邮箱需手动在「设置 → 账户 → POP3/IMAP/SMTP」里开启）
- 使用了登录密码而非「授权码」（特别是 Gmail、QQ、163 等主流邮箱，2023 年后基本禁用账户密码直连）
- 端口选错：587（推荐，TLS）、465（SSL），别用 25（大多被云服务器屏蔽）
- 企业邮箱或阿里云/腾讯云 ECS 默认封禁出站 25 和 465 端口，得提工单解封或改用 587
实操建议：
- 用 smtplib.SMTP_SSL 或 smtplib.SMTP + starttls()，别混用
- 连接前加 timeout=10 参数，避免卡死：smtplib.SMTP("smtp.qq.com", 587, timeout=10)
- 测试连通性优先于发信：能 ehlo() 成功，再试 login()
jinja2 渲染邮件正文：变量不生效或 HTML 被转义
用 jinja2 做模板很顺，但发到邮箱里全是原始 HTML 标签，或者 {{ user.name }} 显示为空——这不是模板语法错，是 MIME 类型和内容处理没对上。
关键点：
- MIMEText 构造时必须显式指定 _subtype="html"，否则默认是 "plain"，浏览器会当纯文本渲染
- 模板里用 {{ content|safe }} 绕过自动转义，但仅限你完全信任 content 来源（比如后台配置的静态文案）
- 别把整个 render_template_string() 结果再用 html.escape() 包一层，这是典型重复转义
示例片段：from email.mime.text import MIMETexthtml = template.render(user={"name": "张三"})msg = MIMEText(html, _subtype="html", _charset="utf-8")
附件中文名乱码：Outlook 打不开或显示问号
Python 发附件时用 add_header("Content-Disposition", ...) 设中文名，结果 Outlook 显示 =?utf-8?b?...?= 或直接乱码。这不是编码错了，是 RFC 2231 的参数格式没达标。
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
立即学习“Python免费学习笔记（深入）”；
正确做法：
- 不要用 filename="中文.pdf" 直接塞进 header
- 改用 add_header("Content-Disposition", "attachment", filename="中文.pdf") —— 注意第三个参数是 keyword arg，email 库内部会按 RFC 自动编码
- 如果手动拼 header，必须用 filename*=utf-8''%E4%B8%AD%E6%96%87.pdf 格式（URL 编码 + 单引号分隔），但强烈不建议手写
- 测试务必用 Outlook / iOS 邮件客户端，Gmail Web 版对乱码容忍度高，会掩盖问题
生产环境发信失败率高：被当成垃圾邮件
本地测试全通，一上服务器就大量进垃圾箱，甚至被拒收。核心不是内容多“营销”，而是发信身份不可信。
必须检查的三项：
- 发信域名是否配置了 SPF 记录（比如 v=spf1 include:smtp.qq.com ~all）
- 是否有 DKIM 签名（QQ/Gmail 官方 SMTP 一般自带，自建 Postfix 需手动配）
- From 地址域名是否与发信 SMTP 域名一致（比如用 smtp.163.com 发 xxx@yourcompany.com，但没配 SPF，163 会拒发或打低分）
- 避免用免费邮箱（如 xxx@gmail.com）作为生产系统发信地址，很多 MTAs 会直接拦截
临时方案可用 Mailgun 或 SendGrid API 替代 SMTP，它们已预配好所有反垃圾基础设施，但要注意 API key 泄露风险和调用量限制。
最常被忽略的是：没设 Reply-To 头。用户点“回复”却发到一个不存在的地址，会被邮件系统判定为可疑行为，长期拉低信誉分。
