Python邮件自动化实战：SMTP发送、IMAP接收与附件处理全指南

直接以从业者口吻开场，不寒暄，切入实际场景，说明这个主题能解决什么问题，适合谁参考。然后按上面构思的章节逐一展开。

做邮件自动化这件事，最早是因为每个月底要给合作方批量发送对账表，几十个附件手工挂载、逐个填写标题，光发送就要磨掉快一个小时，还经常出现漏发、错发。后来我花了一个下午用Python把整个流程接成脚本，彻底告别了这件事。如果你的工作里也有类似的重复性邮件需求——比如定时发送日报、系统报警通知、批量下载邮件附件、解析邮件内容存入数据库——这篇内容应该能帮你少走不少弯路。

简单交代一下适用范围：我会把自动收发邮件涉及的核心模块拆开讲，包括SMTP发信、IMAP收信、MIME格式解析、附件处理、定时调度以及排错经验。整个过程基于Python标准库加少量第三方库实现，适合已经有Python基础、想直接把邮件自动化落地到项目里的开发者，也适合运维、数据分析岗位的同事拿来处理日常邮件流。后面讲的所有代码和配置，都是我在实际项目中验证过的，你可以直接照着抄，再按自己的场景调整。

1. 自动收发邮件的场景边界与协议选型——先想清楚做什么再动手

1.1 我实际遇到过的三类典型需求

邮件自动化的需求看起来都是“收发”，但落到具体场景里差别很大。我梳理了自己做过的几个项目，大致可以分成三类。

第一类是固定内容做定时推送。比如每天上午九点把前一天的销售汇总以附件形式发给指定接收人，或者每周五下午给团队发周报模板。这类需求的痛点是“别漏人、别改错日期、别拖时间”，对发送成功率要求高，但对邮件内容格式几乎不敏感。

第二类是触发式告警通知。系统检测到磁盘空间不足、服务宕机、接口异常时自动发邮件。这类需求对时效性要求高，可能一天几百封，每封内容都不同，必须做到参数化拼装模板，还要考虑重复告警的抑制策略。

第三类是接收端的批量处理。比如每天从指定的业务邮箱里把所有带“发票”字眼的邮件附件下载下来，再批量解析成结构化数据。这类需求的核心是解析准确性，尤其涉及中文文件名、复杂HTML内容和内嵌图片时，处理起来比发送要繁琐得多。

我在跟人要需求的时候通常先问一句：你这业务是要“发出去”，还是“收回来”，还是“收回来再发出去”？别小看这个问题，它直接决定你后面选用哪套协议和库。

1.2 SMTP、IMAP、POP3各干各的，别混用

很多初学者第一次接触邮件协议会被三个缩写绕晕，这里用一个生活化的类比说明：你把邮局想象成一个真实营业厅。

• SMTP是寄件窗口：只管把你的信从你手上送到邮局系统，至于后面怎么中转、怎么抵达，它不负责。它只解决“发”的问题，端口一般是25、465或587。
• POP3像是从信箱里把信全抱回家：它会把服务器上的邮件下载到本地，下载完服务器通常会删除这些邮件（具体看配置）。适合“一次性全量拉取”，但不适合多设备同步，因为你手机上读过的东西电脑上就没了。
• IMAP更像是随时打开云端信箱查看：邮件始终留在服务器上，你在客户端做的读、删、标记操作会同步回服务器。适合需要频繁检索、按条件筛选、多设备协同的场景。

落实到Python编程上，老底子规范做法是——发邮件用smtplib，收邮件用imaplib或poplib。但真正干活的时候我一般遵循一条原则：收邮件优先用IMAP，因为IMAP支持服务端搜索，可以只抓取符合条件的邮件，而POP3必须把整封邮件下载下来才能判断是不是你要的。如果你的业务是每天精确找几封关键邮件去处理，IMAP能省下大把带宽和解析时间。

1.3 三种组合方式怎么选

我整理了一个选型参考表，方便你按场景直接对号入座：

yagmail这个库是我后期才接触的，它在smtplib基础上做了很重的封装，链接邮箱一句话、发带附件邮件一句话。但依赖库较重，在干净的生产环境里我倾向于直接用标准库，能少装一个依赖就少一个。

2. 发送邮件：从smtplib到yagmail的完整落地

2.1 基础配置与授权码准备

发送邮件的核心是SMTP协议。官方标准库smtplib负责底层的邮件传输，email.mime负责构筑邮件内容本体。两者配合使用的流程大致是：先构造一封符合RFC 822格式的邮件对象，再调用smtplib连接服务器、登录、发送。

提到配置就不得不说授权码。现在国内主流邮箱服务商基本都关闭了“密码直接登录SMTP”的开关，你得在邮箱设置中单独开启SMTP服务，并生成一个授权码。这个授权码跟登录密码一样敏感，建议放在环境变量里而不是直接写进代码。

export SMTP_USER="your_account@example.com" export SMTP_AUTH_CODE="your_auth_code" export SMTP_HOST="smtp.example.com" export SMTP_PORT="465"

需要注意，465端口走的是SSL加密，587端口走的是STARTTLS。现在的服务商基本都是223或者双端口同时开放，我习惯优先用465，因为SMTP_SSL一句话就完成加密连接，不用额外处理starttls()的握手。

2.2 正文、附件、HTML三合一的构建方式

构造邮件内容容易踩的坑是：不知道MIMEText、MIMEImage、MIMEBase各自的定位，导致发送出去的HTML邮件显示异常或附件名称乱码。这里给你一套我长期使用的解决方案。

先说纯文本邮件和HTML邮件怎么选。内部告警邮件我默认用HTML格式，因为可以在正文里直接渲染表格、加粗关键数字，接收人看起来直观。HTML正文必须用MIMEText(html_content, "html", "utf-8")包裹，附件则是用MIMEBase把文件内容读入再设置Content-Disposition。

一段能同时发正文和附件的核心代码长这样：

import smtplib import os from email.mime.multipart import MIMEMultipart from email.mime.text import MIMEText from email.mime.base import MIMEBase from email import encoders from email.header import Header def send_mail_with_attachment(subject, html_body, to_list, file_paths=None): msg = MIMEMultipart() msg["From"] = os.environ["SMTP_USER"] msg["To"] = ", ".join(to_list) msg["Subject"] = Header(subject, "utf-8") msg.attach(MIMEText(html_body, "html", "utf-8")) if file_paths: for file_path in file_paths: with open(file_path, "rb") as f: part = MIMEBase("application", "octet-stream") part.set_payload(f.read()) encoders.encode_base64(part) filename = os.path.basename(file_path) part.add_header( "Content-Disposition", "attachment", filename=("utf-8", "", filename), ) msg.attach(part) with smtplib.SMTP_SSL( os.environ["SMTP_HOST"], int(os.environ["SMTP_PORT"]), timeout=30 ) as server: server.login(os.environ["SMTP_USER"], os.environ["SMTP_AUTH_CODE"]) server.sendmail(os.environ["SMTP_USER"], to_list, msg.as_string())

注意上面的filename=("utf-8", "", filename)写法，这里涉及RFC 2231编码规范，能解决中文附件名在部分邮箱客户端里乱码的问题。如果直接传filename=filename，Windows上常见Outlook或Foxmail会把中文名显示为乱码，这个坑我踩过之后一直沿用现在的写法。

刚接触邮件处理的人可能不理解为什么附件要经过encoders.encode_base64，其实原因是MIME格式只允许ASCII字符传输，附件内容是二进制，必须先编码成可打印的ASCII再封装。类似地，正文用MIMEText会自动选择合适的编码方式，但明确声明utf-8始终是最稳妥的。

2.3 群发、多附件、重试机制的实际经验

群发这件事要分清两类场景：你是给一批人发同一封邮件，还是给不同人发内容部分不同的邮件。

如果是发同一封邮件，直接在To字段里用逗号拼接多个收件人即可，一次smtplib连接就能完成。我见过一些代码用循环一封封发，服务器连接反复建立又断开，不仅慢，还可能触发服务商的反垃圾策略，严重时会被临时限制SMTP发信。正确做法是：建立一次连接，把to_list传进sendmail，一封走完。

如果是给不同人发定制内容，比如每个人的业绩数据都不一样，那就不可能只发一封了。我的做法是：把模板的公共部分抽出来，个人数据用字典灌入，循环拼接HTML后仍在一次连接内发送。注意这里别在循环里反复SMTP_SSL，否则每次都要SSL握手和登录，性能损耗很大。

重试机制也是实际项目中容易被忽略的部分。网络抖动、服务商临时限流，都可能让sendmail抛出异常。我通常会封装一层带重试的装饰器，网络类错误重试三次，间隔递增。但也要小心：重试可能造成收件人收到重复邮件，所以重试前最好先确认邮件确实没有送达；不过电子邮件协议本身不保证“确切送达与否”的回执，实际项目中日常发送两次重复的后果可接受，告警类邮件则建议加唯一消息ID去做去重。

一个更稳妥的做法是把待发送邮件序列化后写入本地队列，由独立进程消费队列并发送。这样做的好处是程序崩溃、服务器宕机时邮件不会凭空消失，重启后队列自动恢复。对频率不高的业务邮件来说，本地队列+重试机制已经足够应对大部分异常。

3. 接收邮件：IMAP检索与MIME解析的细节处理

3.1 连接IMAP和搜索引擎语法

接收邮件的链路比发送复杂不少，因为你要面对的现实是：邮件内容五花八门，有纯文本、有超文本标记语言、有内嵌图片、有嵌套的多部分结构，还要考虑字符编码和附件编码。如果只写“连接IMAP然后遍历所有邮件”，100封以内还行，到了上千封性能就崩了，所以在服务端过滤是必须的。

用imaplib连接邮箱的代码不算复杂：

import imaplib import email import os from email.header import decode_header def fetch_emails(search_criteria="ALL"): host = os.environ["IMAP_HOST"] user = os.environ["SMTP_USER"] auth_code = os.environ["SMTP_AUTH_CODE"] conn = imaplib.IMAP4_SSL(host) conn.login(user, auth_code) conn.select("INBOX") status, message_numbers = conn.search(None, search_criteria) message_numbers = message_numbers[0].split() emails = [] for num in message_numbers: status, msg_data = conn.fetch(num, "(RFC822)") raw_email = msg_data[0][1] msg = email.message_from_bytes(raw_email) emails.append(msg) conn.logout() return emails

这段代码里最关键的是conn.search(None, search_criteria)，search_criteria是IMAP搜索引擎语法。常用条件包括：

• ALL：全部邮件。
• UNSEEN：未读邮件。
• FROM "sender@example.com"：指定发件人。
• SUBJECT "报表"：标题包含关键字。
• SINCE "01-Jan-2024"：某个日期之后。
• (UNSEEN FROM "boss@example.com" SINCE "01-Jan-2024")：括号组合多条件，注意条件之间用空格分隔，整体是一个字符串。

掌握这套语法后，你完全可以在服务器端先把候选邮件压缩到几十封再逐封解析，效率比全量拉取高出一个量级。

3.2 解析multipart邮件的正确姿势

拿到了邮件原始对象后，真正考验人的是解析。因为RFC 822格式的邮件可能是嵌套结构：外层是multipart/mixed，里面又套了一层multipart/alternative，这层里同时含纯文本部分和HTML部分，甚至还有multipart/related用来内嵌图片。

解析邮件内容的正确思路是递归，不要去假设“邮件内容就是get_payload()[0]”。我用下面这段代码做通用提取：

from email.header import decode_header def decode_mime_header(header_value): if header_value is None: return "" decoded_parts = decode_header(header_value) result = [] for part, charset in decoded_parts: if isinstance(part, bytes): result.append(part.decode(charset or "utf-8", errors="replace")) else: result.append(part) return "".join(result) def extract_email_content(msg): subject = decode_mime_header(msg.get("Subject")) sender = decode_mime_header(msg.get("From")) if msg.is_multipart(): text_content = "" html_content = "" attachments = [] for part in msg.walk(): content_type = part.get_content_type() content_disposition = str(part.get("Content-Disposition")) if "attachment" in content_disposition: attachments.append(part) elif content_type == "text/plain" and not text_content: text_content = part.get_payload(decode=True).decode( part.get_content_charset() or "utf-8", errors="replace" ) elif content_type == "text/html" and not html_content: html_content = part.get_payload(decode=True).decode( part.get_content_charset() or "utf-8", errors="replace" ) return sender, subject, text_content, html_content, attachments else: content_type = msg.get_content_type() body = msg.get_payload(decode=True).decode( msg.get_content_charset() or "utf-8", errors="replace" ) return sender, subject, body if content_type == "text/plain" else "", body, []

msg.walk()是解析multipart邮件最常用的方式，它会递归遍历邮件里的所有MIME部分。遍历时通过get_content_type()判断这块内容到底是纯文本、HTML还是附件，再用get_content_disposition()判断是内嵌资源还是真正的附件。

有个细节必须注意：get_payload(decode=True)拿回来的是原始字节，没有解码的话中文内容一定是乱码。解码时要优先使用get_content_charset()返回的字符集，不要硬编码UTF-8——有些老系统发来的邮件是GB2312或者GBK编码，硬按UTF-8解出来的就是一堆乱码字符。

3.3 中文乱码与附件文件名处理

接收中文邮件最容易翻车的两个地方，一是正文编码，二是附件文件名。正文编码问题上面已经提过，decode_header和解码字符集是核心；附件文件名则通常藏在一个比较隐蔽的字段里。

附件部分的Content-Disposition里有filename，Content-Type里可能有name，两者都可能经过编码。我在实际开发中遇到最多的情况是：文件名是=?UTF-8?B?...?=这种Base64编码格式，直接用get_param("filename")拿到的还是编码后的字符串，必须用decode_header解析。

一个可靠的附件名提取方式如下：

def extract_attachment_filename(part): filename = part.get_filename() if not filename: return "unnamed" decoded = decode_mime_header(filename) return decoded

还有一类情况是文件名被截断，尤其是老代码里用错误方式添加附件头时，可能导致接收端拿到的文件名不完整。我的经验是：解析附件时先规范地走一步decode_header，实在解析不出来就在日志里记录原始头信息，方便排查。

附件保存的部分建议按照业务键值分目录存放，不要全部丢进同一个目录。比如按发件人、日期、主题关键字的组合建目录，这样后续人工核验时非常直观。

4. 把收发变成自动化任务：调度与守护

4.1 定时任务与守护进程

脚本写完只能手动跑，离“自动化”还差一步——调度。如果你是Linux服务器环境，最原生的方案是crontab，比如每天上午九点发日报：

0 9 * * 1-5 cd /path/to/project && /usr/bin/python3 send_daily_report.py >> /var/log/mail_auto.log 2>&1

这里重点提两点。第一，cron环境变量跟登录shell不一样，直接写python可能找不到解释器，建议在cron里用绝对路径，或者在脚本开头用#!/usr/bin/env python3指定解释器。第二，脚本里的日志一定要重定向到文件，因为cron的输出只会发给当前用户的邮箱，不重定向的话排查问题非常困难。

如果更复杂的调度逻辑——比如希望每天在指定时间点发邮件、每周工作日循环提取附件——可以考虑APScheduler库。它的并发模型简单，BackgroundScheduler可以直接嵌入你的主进程，还能用CronTrigger实现类似cron的表达方式。

4.2 失败重试、日志和告警闭环

自动化任务运行起来之后，最怕的不是报错，而是“静默失败”。邮件脚本由于网络、服务商策略、账户状态等因素都可能运行失败，如果没有任何日志和告警，你可能在客户投诉之后才发现系统已经停了三天。

我现在做的项目里，邮件自动化的日志级别配置大致是这样的：

• DEBUG级别记录每次收发邮件的连接状态、耗时、邮件大小。
• INFO级别记录邮件主题、收件人、是否有附件。
• WARNING级别记录授权码即将过期、连接超时、搜索无结果等情况。
• ERROR级别记录登录失败、发送失败、解析异常。

日志不只是给人看的，还是给监控脚本看的。在重试机制已经把所有自动恢复的可能性用尽之后，任务应当发出人工告警。告警本身可以走另一套独立渠道——比如企业内部的机器人群或者简单的HTTP回调——别把“能用的断电”和“报警器”接在同一条电路上。

我自己习惯的做法是：把发送函数和接收函数全部封装成独立模块，在入口处统一捕获异常。任何一级失败都会先尝试重试，重试不成功再进入人工告警通道。这样既保证日常业务不受单次偶发故障影响，也能在关键异常发生时及时感知。

5. 实测踩坑记录：授权码、超时、乱码与邮件头异常

5.1 授权码过期和账户锁定风险

授权码是自动化邮件最容易踩的坑。我之前一个项目跑了半年，某天突然所有邮件都发不出去，日志显示SMTPAuthenticationError。查了半天才发现，服务商对授权码有有效期限制，过期之后界面显示正常，但底层SMTP登录被拒绝。

这类问题最直观的解法是：把授权码和账户配置集中管理，并在日志中记录授权码的签发时间、过期时间，提前一周让运维更换。如果你用的是企业邮箱，邮件服务商还可能因为异地登录、短时间大量发送触发风控，导致账户临时锁定。遇到这种状况，盲目的重试只会延长锁定期，正确的处理是停止发送、人工登录邮箱确认状态、等待风控解除。

5.2 超时时间和网络环境的坑

默认情况下，smtplib和imaplib的某些操作没有超时时间或者超时时间很长。一个简单的网络抖动，就能让脚本卡死在socket.read那里，整个调度任务迟迟无法结束。我自己在写连接层的时候，给SMTP_SSL和IMAP4_SSL都显式传了timeout=30，同时在外层再加一个函数级别的时间限制，双保险确保任务不会被网络问题永久挂起。

在容器化环境里需要注意出口IP和端口。很多服务器只开放了常见的80、443端口，而SMTP的465、587、25以及IMAP的993端口可能不在白名单内。上线前花两分钟用telnet或Python测试连通性，比真正跑业务的时候才发现发不出去要省心得多。

5.3 邮件头字段的误导性

收件解析时有一批字段特别容易误导新手：From、Return-Path、Sender、Envelope-From。日常处理IMAP收到的邮件，我基本以From为主，但要注意From里除了邮箱地址还带有一个显示名称，格式是张三 <zhangsan@example.com>，需要正则或者email.utils.parseaddr来提取地址部分。

还有一个比较隐蔽的问题：部分邮件客户端发送的邮件把发件人名用B编码写在From字段里，直接打印是=?UTF-8?B?...?=。用decode_header处理是标准办法，但也有极少数个性化客户端生成的编码在解码时会抛异常，遇到这种邮件不能直接让整个解析进程崩溃，应该捕获异常后降级为原始字符串并记录日志。

5.4 常见报错对照表

最后给一张我长期排错过程中整理的报错对照表，很多新人在社区里问的问题都可以在这里找到答案：

这七类问题我几乎每周都会在社区交流中看到有人问，其中前两类属于配置和环境问题，后几类属于代码层面的细节。把这张表收藏下来，上线出问题的时候逐条排查，大多数情况十分钟内能定位。

我实际操作中还有一个体会：邮件自动化不只是写脚本的事，它更像一个需要持续维护的小型链路。账户状态、网络策略、服务商规则、目标邮箱的解析能力，这些外部因素都在动态变化。刚上线时跑得好不代表三个月后还正常，定期抽查日志、定期人工确认关键邮件确实送达，比把所有希望放在“脚本能一直稳定运行”这个假设上要靠谱得多。如果这篇文章能帮你少踩两个坑，那也算值了。