1. 项目概述：为什么用Python发邮件是必备技能
在自动化办公和数据监控的日常里，自动发送邮件是个高频需求。无论是定时推送一份数据分析报告，还是在服务器异常时第一时间向你的手机发送告警，或者批量给用户发送通知，手动去点“发送”按钮显然不现实。Python凭借其简洁的语法和强大的库生态，成了实现这类任务的首选工具。很多人一听到“编程发邮件”就觉得门槛很高，涉及到复杂的网络协议。其实不然，Python标准库里的smtplib和email模块已经把SMTP（简单邮件传输协议）的底层细节封装得非常友好，你只需要关注“谁发”、“发给谁”、“发什么内容”这几个核心问题。这篇文章，我就以一个老开发的身份，带你从零开始，手把手搞定用Python发送邮件的全过程，从最基础的文本邮件到带附件的复杂邮件，再到如何避开那些新手常踩的“坑”，比如授权码、端口选择、编码问题等。无论你是想给自己的小工具增加一个通知功能，还是为公司的自动化流程搭建一个邮件通知模块，这篇指南都能给你一套可直接复用的解决方案。
2. 核心原理与准备工作
2.1 SMTP协议与Python模块简介
SMTP是互联网上发送电子邮件的标准协议，你可以把它想象成邮局系统。你的Python程序就是寄件人，它需要找到一家“邮局”（SMTP服务器），把写好的信（邮件内容）交给它，由它负责投递到收件人的“邮箱”（接收邮件服务器）。Python的smtplib模块就是专门用来和SMTP服务器打交道的“邮递员”，它负责建立连接、身份认证和发送指令。而email模块则是“信封和信纸”的制造厂，它帮你把邮件的发件人、收件人、主题、正文、附件等各部分，按照严格的格式组装成一个完整的、SMTP服务器能识别的数据包。
这里有一个关键点：你不能直接用你的邮箱密码去登录SMTP服务器。出于安全考虑，主流的邮箱服务商（如Gmail、QQ邮箱、163邮箱、Outlook）都要求使用“授权码”或“应用专用密码”。这相当于为你的Python程序单独生成了一把钥匙，而不是给你家大门的万能钥匙。即使这把钥匙泄露了，也不会危及你邮箱账户的全部安全。所以，第一步永远是去你的邮箱设置里生成这个授权码。
2.2 环境准备与授权码获取
你不需要安装任何额外的第三方库，因为smtplib和email都是Python的标准库，只要你安装了Python（建议3.6以上版本），它们就已经就位了。准备工作主要是获取以下信息：
SMTP服务器地址和端口：不同邮箱服务商不同。常见的有：
- QQ邮箱/QQ企业邮箱：
smtp.qq.com， 使用SSL加密的端口是465， 使用TLS加密的端口是587。 - 163/126邮箱：
smtp.163.com， 端口同上。 - Gmail：
smtp.gmail.com， 端口587(TLS) 或465(SSL)。 - Outlook/Hotmail：
smtp.office365.com， 端口587(TLS)。
- QQ邮箱/QQ企业邮箱：
发件人邮箱账号：你的完整邮箱地址。
授权码（App Password）：这是最关键的一步。以QQ邮箱为例，登录网页版后，在“设置”->“账户”中找到“POP3/IMAP/SMTP服务”选项，开启服务后会提示你生成授权码。Gmail用户需要在Google账户的“安全性”设置中，开启“两步验证”后，才能生成“应用专用密码”。请务必妥善保管这个16位（或其他长度）的字符串，它就是你的程序密码。
注意：千万不要将授权码直接硬编码在提交到公开仓库的代码里！一个标准的做法是将其存储在环境变量或本地的配置文件中。例如，在代码所在目录创建一个
.env文件（记得加入.gitignore），内容为EMAIL_PASSWORD=你的授权码，然后在Python中使用os.getenv('EMAIL_PASSWORD')来读取。
3. 从零开始：发送第一封纯文本邮件
让我们从最简单的场景开始：发送一封只有纯文本正文的邮件。这个过程清晰地展示了使用smtplib和email模块的标准流程。
3.1 构建邮件内容对象
首先，我们需要用email模块来“撰写”邮件。MIMEText类专门用于创建文本邮件。
from email.mime.text import MIMEText import smtplib # 1. 构建邮件内容 msg = MIMEText('你好，这是一封来自Python的测试邮件。', 'plain', 'utf-8') msg['From'] = 'your_email@qq.com' # 发件人 msg['To'] = 'recipient@example.com' # 收件人 msg['Subject'] = 'Python邮件测试' # 邮件主题这里有几个细节：
MIMEText的第一个参数是邮件正文。- 第二个参数
‘plain’表示这是纯文本。如果要发送HTML格式的邮件，则改为‘html’。 - 第三个参数
‘utf-8’指定编码，确保中文不会乱码。 msg[‘From’]和msg[‘To’]是邮件头信息，它们告诉服务器这封信是谁寄的、要寄给谁。注意，‘To’字段可以是一个由逗号分隔的字符串，用于发送给多人，例如‘a@a.com, b@b.com’。
3.2 连接SMTP服务器并发送
邮件“写”好后，就该交给“邮递员”smtplib了。
# 2. 连接SMTP服务器并发送 smtp_server = 'smtp.qq.com' smtp_port = 465 # 使用SSL加密 from_addr = 'your_email@qq.com' password = '你的16位QQ邮箱授权码' # 警告：实际使用时请从环境变量读取！ try: # 创建SSL安全连接 server = smtplib.SMTP_SSL(smtp_server, smtp_port) # 调试模式，会在控制台打印与服务器的所有通信，便于排查问题 server.set_debuglevel(1) # 登录邮箱账户 server.login(from_addr, password) # 发送邮件 # sendmail 参数：发件人，收件人列表（可以是字符串或列表），邮件内容（as_string()方法将MIME对象转为字符串） server.sendmail(from_addr, ['recipient@example.com'], msg.as_string()) print("邮件发送成功！") except smtplib.SMTPException as e: print(f"邮件发送失败: {e}") finally: # 关闭连接 server.quit()实操心得：
- 端口选择：
465端口使用SMTP_SSL在建立连接之初就进行加密，而587端口通常先使用SMTP建立普通连接，然后通过starttls()方法升级为加密连接。后者更灵活，是当前推荐的方式。使用587端口的代码略有不同：server = smtplib.SMTP(smtp_server, 587) server.starttls() # 升级为加密连接 server.login(from_addr, password) # ... 后续发送操作相同 - 调试：在开发阶段，将
server.set_debuglevel(1)打开非常有用，你能看到和服务器“对话”的全过程，如果登录失败或发送出错，从这些日志里能找到第一手线索。 - 异常处理：网络不稳定、授权码错误、服务器拒绝等都可能导致发送失败。用
try...except包裹核心代码是生产环境中的基本操作，必要时可以加入重试逻辑。
4. 进阶功能：发送HTML邮件与带附件的邮件
只会发纯文本邮件显然不够用。工作报告需要精美的排版，监控周报需要嵌入图表，这些都需要HTML邮件。而发送会议纪要、数据文件等，则离不开附件功能。
4.1 发送HTML格式邮件
发送HTML邮件和发送纯文本邮件在步骤上几乎一样，唯一的区别在于构建MIMEText对象时，将第二个参数改为‘html’，并将HTML字符串作为正文内容。
from email.mime.text import MIMEText html_content = """ <!DOCTYPE html> <html> <body> <h2 style="color: blue;">每周数据报告</h2> <p>本周系统运行平稳，关键指标如下：</p> <ul> <li>用户活跃数： <strong>15,432</strong></li> <li>订单成功率： <strong>99.2%</strong></li> <li>平均响应时间： <strong>128ms</strong></li> </ul> <p>详情请查看<a href=\"https://your-dashboard.com\">内部数据看板</a>。</p> </body> </html> """ msg = MIMEText(html_content, 'html', 'utf-8') msg['From'] = from_addr msg['To'] = to_addr msg['Subject'] = '【自动化周报】系统运行数据' # ... 后续连接服务器和发送的代码与之前相同注意事项：
- 样式内联：很多邮件客户端（如Outlook、Gmail网页版）对
<style>标签或外部CSS支持不佳。为了确保样式显示一致，最好将CSS样式以内联形式（style=””）写在HTML标签内部。 - 图片嵌入：如果HTML邮件中有图片，并且希望收件人离线也能查看，不能简单使用网络图片链接（有些邮件客户端会屏蔽）。这时需要将图片作为附件嵌入（Content-ID），这涉及到
MIMEMultipart和MIMEImage，稍显复杂。对于简单的报告，使用网络链接并做好链接失效的备选说明是更务实的做法。
4.2 发送带附件的邮件
发送附件需要用到MIMEMultipart类。你可以把它看作一个“混合容器”，这个容器里既可以装文本正文（MIMEText），也可以装各种附件（MIMEApplication,MIMEImage等）。
from email.mime.multipart import MIMEMultipart from email.mime.text import MIMEText from email.mime.application import MIMEApplication import os # 创建混合类型的邮件主体 msg = MIMEMultipart() msg['From'] = from_addr msg['To'] = to_addr msg['Subject'] = '带附件的测试邮件 - 数据分析报告.pdf' # 添加文本正文 text_part = MIMEText('您好，本次的数据分析报告请查收，详情见附件。', 'plain', 'utf-8') msg.attach(text_part) # 添加附件 file_path = './weekly_report.pdf' with open(file_path, 'rb') as f: # MIMEApplication 适合用于二进制文件，如pdf, zip, excel等 att = MIMEApplication(f.read()) # 为附件添加头部信息，指定文件名 att.add_header('Content-Disposition', 'attachment', filename=os.path.basename(file_path)) # 可选：指定附件类型，帮助邮件客户端识别 att.add_header('Content-Type', 'application/octet-stream', name=os.path.basename(file_path)) msg.attach(att) # ... 后续连接服务器和发送的代码与之前相同实操心得：
- 文件名编码：如果附件文件名包含中文，直接使用
os.path.basename可能会导致乱码。需要对其进行编码处理。一种常见的方法是使用email.header.Header类：from email.header import Header filename = Header(‘中文报告.pdf’, ‘utf-8’).encode() att.add_header(‘Content-Disposition’, ‘attachment’, filename=filename) - 大附件处理：对于非常大的文件，一次性读入内存（
f.read()）可能造成压力。可以考虑分块读取，但对于SMTP发送来说，通常附件大小会被邮件服务商限制（如25MB），所以这个问题不常遇到。如果必须发送大文件，更常见的做法是上传到云存储，然后在邮件正文中分享下载链接。 - 多个附件：只需重复
attach操作即可，msg.attach(att1),msg.attach(att2)。
5. 实战封装与高级配置
当你掌握了基本操作后，为了在多个项目中复用，也为了代码更清晰健壮，将其封装成一个类或函数是必然选择。同时，我们还需要考虑一些生产环境中会遇到的实际问题。
5.1 构建一个可复用的邮件发送类
下面是一个简化但功能相对完整的邮件发送类示例：
import smtplib from email.mime.text import MIMEText from email.mime.multipart import MIMEMultipart from email.mime.application import MIMEApplication from email.header import Header import os class EmailSender: def __init__(self, smtp_server, smtp_port, username, password, use_tls=True): """ 初始化邮件发送器 :param smtp_server: SMTP服务器地址 :param smtp_port: 端口 :param username: 发件邮箱 :param password: 授权码 :param use_tls: 是否使用TLS (端口587)，否则使用SSL (端口465) """ self.smtp_server = smtp_server self.smtp_port = smtp_port self.username = username self.password = password self.use_tls = use_tls self.server = None def connect(self): """建立与SMTP服务器的连接""" try: if self.use_tls: self.server = smtplib.SMTP(self.smtp_server, self.smtp_port) self.server.starttls() # 升级为TLS加密连接 else: self.server = smtplib.SMTP_SSL(self.smtp_server, self.smtp_port) # SSL连接 self.server.login(self.username, self.password) print("SMTP服务器连接成功。") except Exception as e: print(f"连接SMTP服务器失败: {e}") raise def send_email(self, to_addrs, subject, content, content_type='plain', attachments=None): """ 发送邮件 :param to_addrs: 收件人，字符串或列表 :param subject: 邮件主题 :param content: 邮件正文内容 :param content_type: 正文类型，'plain' 或 'html' :param attachments: 附件路径列表，如 [‘./file1.pdf‘, ‘./data.zip’] """ if not self.server: self.connect() # 创建邮件主体 if attachments: msg = MIMEMultipart() # 添加正文部分 text_part = MIMEText(content, content_type, 'utf-8') msg.attach(text_part) else: msg = MIMEText(content, content_type, 'utf-8') # 设置邮件头 msg['From'] = self.username msg['To'] = ', '.join([to_addrs] if isinstance(to_addrs, str) else to_addrs) msg['Subject'] = Header(subject, 'utf-8') # 处理主题中文编码 # 添加附件 if attachments: for file_path in attachments: if os.path.exists(file_path): with open(file_path, 'rb') as f: att = MIMEApplication(f.read()) # 处理中文文件名 basename = os.path.basename(file_path) filename = Header(basename, 'utf-8').encode() att.add_header('Content-Disposition', 'attachment', filename=filename) msg.attach(att) else: print(f"警告：附件文件不存在，已跳过 - {file_path}") # 发送邮件 try: self.server.sendmail(self.username, to_addrs, msg.as_string()) print(f"邮件发送成功至 {to_addrs}") except Exception as e: print(f"邮件发送失败: {e}") raise def quit(self): """关闭连接""" if self.server: self.server.quit() print("SMTP连接已关闭。") # 使用示例 if __name__ == '__main__': # 配置信息（应从环境变量或配置文件中读取） config = { 'smtp_server': 'smtp.qq.com', 'smtp_port': 587, 'username': 'your_email@qq.com', 'password': os.getenv('QQ_EMAIL_PASSWORD'), # 从环境变量读取密码 'use_tls': True, } sender = EmailSender(**config) try: sender.connect() # 发送纯文本邮件 sender.send_email( to_addrs='recipient1@example.com', subject='测试纯文本', content='这是一封纯文本测试邮件。' ) # 发送带HTML和附件的邮件 sender.send_email( to_addrs=['recipient1@example.com', 'recipient2@example.com'], subject='周报与数据', content='<h1>本周总结</h1><p>详情见附件。</p>', content_type='html', attachments=['./weekly_report.pdf', './data.xlsx'] ) finally: sender.quit()这个类将连接、发送、关闭连接等逻辑封装起来，支持TLS/SSL、HTML、多收件人、多附件，并初步处理了中文编码问题，可以直接集成到你的项目中。
5.2 异步发送与连接池考量
对于需要高频发送邮件（如批量通知）的场景，同步发送（发完一封再发下一封）效率太低。此时可以考虑异步发送。但请注意，smtplib本身是同步的。实现异步通常有两种思路：
- 多线程/多进程：为每一批邮件或每一个发送任务开启一个独立的线程或进程。这种方法简单，但线程/进程管理不当会造成资源浪费。可以使用
concurrent.futures库中的ThreadPoolExecutor来管理线程池。 - 异步IO（asyncio）：更现代高效的方式。但
smtplib没有原生异步支持。你可以使用第三方库如aiosmtplib，它提供了异步的SMTP客户端。代码模式如下：import aiosmtplib from email.message import EmailMessage async def send_async(): message = EmailMessage() message[“From”] = from_addr message[“To”] = to_addr message[“Subject”] = “异步测试” message.set_content(“异步发送邮件内容”) await aiosmtplib.send(message, hostname=“smtp.qq.com”, port=587, username=from_addr, password=password, use_tls=True)
连接池：对于超高频发送（如每分钟数百封），频繁建立和断开SMTP连接（三次握手、TLS协商）开销巨大。一个优化方案是维护一个持久的SMTP连接池。发送邮件时从池中取出一个已认证的连接，用完放回，避免重复登录。这需要更复杂的代码来管理连接的生命周期、超时和重连。在绝大多数应用场景下，每发送一封邮件就建立一次连接是可以接受的。
6. 常见问题排查与安全实践
在实际操作中，你几乎一定会遇到一些问题。下面我整理了一份“踩坑”清单和对应的解决方案。
6.1 典型错误与解决方案速查表
| 错误现象或问题 | 可能原因 | 解决方案 |
|---|---|---|
smtplib.SMTPAuthenticationError: (535, b‘Login Fail’) | 1. 授权码错误（最常见）。 2. 邮箱未开启SMTP服务。 3. 使用了邮箱登录密码而非授权码。 4. 尝试登录的账号与发件人不符。 | 1. 仔细核对并重新生成授权码。 2. 登录网页邮箱，在设置中开启POP3/SMTP服务。 3. 确认使用的是“授权码”。 4. 确保 login用的账号和msg[‘From’]一致。 |
smtplib.SMTPConnectError或连接超时 | 1. SMTP服务器地址或端口写错。 2. 网络问题（防火墙、代理）。 3. 服务器暂时不可用。 | 1. 核对服务商提供的正确地址和端口。 2. 尝试关闭代理或更换网络。 3. 稍后重试。使用 server.set_debuglevel(1)查看具体卡在哪一步。 |
ssl.SSLError相关错误 | 1. Python版本过旧，SSL库不兼容。 2. 系统时间不正确，导致SSL证书验证失败。 | 1. 升级Python到较新版本（如3.7+）。 2. 同步系统时间。临时可尝试创建不验证证书的上下文（生产环境不推荐）： import ssl; context = ssl.create_default_context(); context.check_hostname = False; context.verify_mode = ssl.CERT_NONE，然后在SMTP_SSL中传入context=context。 |
| 邮件发送成功但收不到 | 1. 被收件箱的垃圾邮件规则过滤。 2. msg[‘From’]或msg[‘To’]格式错误。3. 发送频率过高被服务商临时限制。 | 1. 检查垃圾邮件箱。让发件人将你的发件地址加入白名单。 2. 确保地址是完整的邮箱格式。 3. 降低发送频率，或使用具备高信誉度的商业邮件发送服务（如SendGrid, Amazon SES）。 |
| 邮件正文或附件名中文乱码 | 未正确指定编码。 | 1. 在创建MIMEText或设置Header时，明确指定charset=‘utf-8’。2. 对中文文件名使用 email.header.Header进行编码。 |
| Gmail发送失败，提示“安全性较低的应用的访问权限” | Gmail默认阻止被认为“安全性较低”的应用登录。 | 1. （不推荐）在Google账户设置中允许“安全性较低的应用”访问。 2. （推荐）按照Gmail要求，开启“两步验证”，然后使用生成的16位“应用专用密码”进行登录。 |
6.2 安全与最佳实践
- 绝不要硬编码密码：这是最重要的安全准则。将授权码存储在环境变量、专用的配置文件（如
config.yaml、.env）或密钥管理服务中。在代码中通过os.environ.get(‘KEY’)来读取。 - 使用TLS加密：优先使用
587端口和starttls()方法，这是更现代、更受推荐的加密方式。 - 限制发送频率和量：个人邮箱的SMTP服务通常有每日发送上限（如QQ邮箱是每天500封），且短时间内高频发送极易被判定为垃圾邮件甚至封号。对于营销或大量通知，请使用专业的邮件发送服务（ESPs）。
- 设置合适的邮件头：可以设置
Message-ID、Date等头信息，让你的邮件更规范。对于批量发送，合理使用Bcc（密送）而非To或Cc，可以保护收件人隐私。 - 处理退信（Bounce）：在生产环境中，部分邮件会因地址无效、邮箱已满等原因被退回。成熟的邮件发送系统需要监听和处理这些退信通知，通常涉及解析返回的DSN（投递状态通知）邮件，这是一个相对高级的话题。
- 代码健壮性：加入重试机制（例如，使用
tenacity库）、超时设置和详细的日志记录，确保在临时网络波动或服务短暂不可用时，程序能优雅地处理而非直接崩溃。
通过以上步骤，你不仅能够实现Python发送邮件的基础功能，更能构建一个健壮、可维护、安全的邮件发送模块，从容应对各种实际开发场景。记住，关键不在于记住所有参数，而在于理解SMTP通信的基本模型和email库构建MIME消息的逻辑，这样无论遇到什么需求，你都能快速找到解决方案。
