Flask 集成 Flask-Mail 实现 SMTP 邮件发送详解

拾柒

发布时间：2026-10-11| 2人浏览过

原创

本文介绍在 Flask 框架中调用 SMTP 协议发送电子邮件的完整流程。涵盖 Flask-Mail 扩展安装、通用邮箱参数配置、Message 类构造方法以及标准发送代码示例，附带 SSL/TLS 通道选择与常见报错排查建议，帮助开发者快速集成邮件通知功能。

目标与环境准备

首先需通过系统终端安装官方推荐的邮件路由扩展，该库负责处理底层 SMTP 会话建立、字符集编码及附件序列化。

pip install Flask-Mail

第一步：初始化 SMTP 配置参数

扩展依赖 Flask 应用上下文中的配置字典驱动连接。不同邮件服务商对安全通道与通信端口有强制约定，配置时需严格对齐：

Flask应用配置字典结构与邮箱参数对应关系 — 通过 app.config 映射各厂商 SMTP 地址、端口及安全协议选项

核心字段定义如下：

MAIL_SERVER：SMTP 网关域名，例如 Google 提供 smtp.gmail.com。
MAIL_PORT：TCP 端口号。启用 SSL 包裹传输时固定为 465，启用 STARTTLS 升级时为 587。
MAIL_USERNAME / MAIL_PASSWORD：认证凭据。生产部署时请替换为环境变量读取，防止源码仓库泄露密钥。
MAIL_USE_TLS / MAIL_USE_SSL：协议开关，两者互斥，必须与端口物理规则一致。

第二步：封装邮件消息体对象

Mail 实例化管理

创建全局 Mail 单例后，框架将自动缓存连接池并在 send() 调用时复用会话。其提供的控制方法包含主动终止连接、批量提交队列等能力：

Mail类的核心方法与属性结构 — 封装了连接池管理与异常重试机制的底层 API 概览

Message 数据结构组装

所有待投递载荷需实例化为 Message 对象。构造阶段指定头部元数据，随后填充负载：

from flask_mail import Message

msg = Message(
    subject='业务通知',                 # 邮件标题
    sender='noreply@example.com',       # 发件人标识
    recipients=['user@example.com']     # 主收件人列表
)
msg.body = '感谢您的注册确认。'          # 纯文本兜底视图
# msg.html = '感谢您的注册确认。' # 富文本视图（推荐同时提供）
msg.add_recipient('cc_user@example.com') # 追加抄送
msg.attach(
    filename='invoice.pdf', 
    content_type='application/pdf', 
    data=open_report_data()
)                                      # 嵌入二进制附件

第三步：编写路由并触发发送

将上述组件缝合至 HTTP 请求处理器中，可实现用户交互触发型邮件派发。以下为适配主流加密通道的完整模板：

from flask import Flask
from flask_mail import Mail, Message

app = Flask(__name__)

app.config['MAIL_SERVER'] = 'smtp.gmail.com'
app.config['MAIL_PORT'] = 465              # SSL 专用端口（注：原示例 456 属笔误）
app.config['MAIL_USERNAME'] = 'account@gmail.com'
app.config['MAIL_PASSWORD'] = 'app_specific_pass'
app.config['MAIL_USE_TLS'] = False
app.config['MAIL_USE_SSL'] = True

mail = Mail(app)

@app.route('/trigger_email')
def send_test():
    try:
        msg = Message(
            subject='自动化测试报告',
            sender=app.config['MAIL_USERNAME'],
            recipients=['tester@company.com']
        )
        msg.body = 'Environment check passed.'
        mail.send(msg)
        return '邮件投递成功', 200
    except ConnectionRefusedError:
        return 'SMTP 端口拦截或证书校验失败，请检查网络与安全组策略', 503
    except AuthenticationFailed:
        return '账号密码错误或未开启第三方登录授权', 401

if __name__ == '__main__':
    app.run(debug=True)