maillite 0.1.4

A simple and easy-to-use email sending library with template support

MailLite

一款简单易用的Python邮件发送库，支持HTML模板渲染、附件发送、SSL/TLS加密连接，内置精美的邮件模板。

特性

• 简单集成 — 几行代码即可发送邮件
• 模板引擎 — 基于Jinja2的HTML / 纯文本模板渲染，主题（subject）也支持变量
• 内置模板 — 开箱即用的 welcome（欢迎）和 admonition（系统通知/告警）模板
• 自定义模板 — 支持自定义模板目录，优先级高于内置模板
• 附件支持 — 可附加任意本地文件
• 多种加密 — 支持 SSL（端口 465）和 STARTTLS（端口 587）
• 完整 MIME — 纯文本、HTML、多收件人（To/CC/BCC）、Reply-To 等

安装

pip install maillite

从源码安装（开发模式）：

git clone <repo-url>
cd maillite
pip install -e ".[dev]"

快速开始

发送纯文本邮件

from maillite import EasyMailer

mailer = EasyMailer(
    host="smtp.qq.com",
    port=465,
    username="[e-mail]",
    password="your_auth_code",   # QQ 邮箱请使用授权码
    use_ssl=True,
)

mailer.send(
    to="[e-mail]",
    subject="测试邮件",
    body="这是一封来自 MailLite 的测试邮件。",
)

使用模板发送邮件

mailer.send_template(
    to="[e-mail]",
    subject="欢迎 {{ name }}",
    template_name="welcome",
    context={
        "name": "张三",
        "title": "欢迎加入",
        "message": "感谢您的注册！",
        "action_url": "https://example.com/dashboard",
        "action_text": "进入控制台",
    },
)

发送服务异常告警

import traceback

mailer.send_template(
    to="[e-mail]",
    subject="【{{ severity }}】{{ service_name }} 服务异常",
    template_name="admonition",
    context={
        "name": "运维同学",
        "title": "服务异常通知",
        "subtitle": "系统检测到异常，请及时关注",
        "severity": "严重",
        "service_name": "API Gateway",
        "code": "ERR_502",
        "message": "Connection refused: upstream server 10.0.0.5:8080",
        "occurred_at": "2026-07-08 20:30:00",
        "action_url": "https://monitor.example.com/incidents/123",
    },
)


try:
    a
except Exception as err:
    mailer.send_template(
    to="[e-mail]",
    subject="【{{ severity }}】{{ service_name }} 服务异常",
    template_name="admonition",
    context={
        "name": "运维同学",
        "severity": "严重",
        "service_name": "API Gateway",
        "code": "ERR_502",
        "message": traceback.format_exc(),
        "occurred_at": "2026-07-08 20:30:00"
    },
)

API 参考

EasyMailer(...)

初始化邮件发送器。

参数	类型	默认值	说明
host	str	—	SMTP 服务器地址
port	int	—	SMTP 端口（SSL: 465, TLS: 587, 明文: 25）
username	str	—	SMTP 登录用户名
password	str	—	SMTP 登录密码 / 授权码
use_ssl	bool	True	使用 SSL 连接
use_tls	bool	False	使用 STARTTLS（不可与 use_ssl 同时开启）
default_sender	str	None	默认发件人地址，不填则使用 username
template_dir	str	None	自定义模板目录路径

mailer.send(...)

发送邮件。

参数	类型	说明
to	str / list[str]	收件人
subject	str	邮件主题
body	str	纯文本正文
html	str	HTML 正文（优先于 body）
cc	str / list[str]	抄送
bcc	str / list[str]	密送
sender	str	发件人（覆盖 default_sender）
sender_name	str	发件人显示名
attachments	list[str / dict]	附件列表（见下方说明）
reply_to	str	回复地址

mailer.send_template(...)

使用模板发送邮件。模板通过 Jinja2 渲染，subject 同样支持模板变量。

参数	类型	说明
to	str / list[str]	收件人
subject	str	邮件主题（支持 Jinja2 变量）
template_name	str	模板名称（不含扩展名）
context	dict	模板变量字典
cc	str / list[str]	抄送
bcc	str / list[str]	密送
sender	str	发件人
sender_name	str	发件人显示名
attachments	list[str / dict]	附件列表（见下方说明）
reply_to	str	回复地址

attachments 附件说明

attachments 列表中的每个元素支持两种格式：

1. 文件路径（str）

attachments=["d:/report.pdf", "d:/data.xlsx"]

2. 二进制数据（dict） — 适用于动态生成的图片、文件等

attachments=[
    {
        "filename": "chart.png",
        "data": image_bytes,          # bytes 类型
        "content_type": "image/png",  # 可选，自动根据 filename 推断
    }
]

两种格式可以混合使用：attachments=["d:/report.pdf", {"filename": "chart.png", "data": image_bytes}]

如果同时存在 template_name.html 和 template_name.txt，HTML 版本作为富文本正文，TXT 版本作为纯文本备用正文。

内置模板

welcome — 欢迎模板

紫蓝渐变主题，适用于用户注册、邀请等场景。

变量	说明	默认值
title	头部标题	"欢迎使用 MailLite"
name	收件人称呼	—
message	正文内容	内置默认文案
action_url	CTA 按钮链接	—
action_text	CTA 按钮文案	"立即查看"
help_url	底部帮助链接	—

admonition — 系统通知/告警模板

多主题告警模板，根据 severity 自动切换颜色（红/橙/绿/蓝），适用于系统监控、故障通知、服务恢复、日常通知等场景。

变量	说明	默认值
title	头部标题	"系统通知"
subtitle	头部副标题（小标题）	—
name	收件人称呼	—
body	正文描述段落	—
severity	严重程度	—
service_name	服务标识	—
code	事件编号	—
message	信息内容	—
occurred_at	发生时间	自动填充当前时间（YYYY-MM-DD HH:MM:SS）
action_url	查看详情链接	—
action_text	按钮文案	"查看详情"
sender_name	发件方署名	"MailLite 监控团队"
help_url	底部帮助链接	—

severity 支持以下值："严重" / "critical" (红色)、"警告" / "warning" (橙色)、"成功" / "success" (绿色)、"信息" / "info" (蓝色)，其他值默认蓝色。

自定义模板

创建自己的模板目录并放置 .html / .txt 文件：

my_templates/
├── invoice.html
└── invoice.txt

mailer = EasyMailer(
    host="smtp.qq.com",
    port=465,
    username="[e-mail]",
    password="your_auth_code",
    use_ssl=True,
    template_dir="./my_templates",   # 自定义模板目录
)

mailer.send_template(
    to="[e-mail]",
    subject="发票 #{{ invoice_no }}",
    template_name="invoice",
    context={"invoice_no": "20260708-001", "amount": "¥1,280.00"},
)

自定义目录优先级高于内置模板。如果同名模板存在于两个目录，自定义版本会被使用。也可以在运行时通过 mailer._template_engine.add_template_dir(path) 动态添加模板目录。

运行测试

# 单元测试
python -m pytest tests/ -v

# 集成测试（真实 SMTP 发送）
# PowerShell:
$env:MAILLITE_INTEGRATION="1"
$env:SMTP_HOST="smtp.qq.com"
$env:SMTP_PORT="465"
$env:SMTP_USER="[e-mail]"
$env:SMTP_PASS="your_auth_code"
python -m pytest tests/test_mailer.py -k integration -v

许可证

见 LICENSE 文件。