Metadata-Version: 2.1
Name: maillite
Version: 0.1.5
Summary: A simple and easy-to-use email sending library with template support
Home-page: https://github.com/zhenzi0322/maillite
Author: zhenzi0322
Author-email: zhenzi0322 <82131529@qq.com>
License: MIT
Requires-Python: >=3.8
description-content-type: text/markdown
Description:
 
 <p align="center">
   <h1>MailLite</h1>
   <b>一款简单易用的Python邮件发送库，支持HTML模板渲染、附件发送、SSL/TLS加密连接，内置精美的邮件模板。</b>
   <br><br>
   <a href="https://pypi.org/project/maillite/"><img src="https://img.shields.io/pypi/v/maillite.svg" alt="PyPI version"></a>
   <a href="https://pypi.org/project/maillite/"><img src="https://img.shields.io/pypi/pyversions/maillite.svg" alt="Python"></a>
   <a href="https://github.com/zhenzi0322/maillite/blob/main/LICENSE"><img src="https://img.shields.io/pypi/l/maillite.svg" alt="License"></a>
 </p>
 
 -----
 
 ## 特性
 
 - **简单集成** — 几行代码即可发送邮件
 - **模板引擎** — 基于`Jinja2`的`HTML` / 纯文本模板渲染，主题（`subject`）也支持变量
 - **内置模板** — 开箱即用的 `welcome`（欢迎）和 `admonition`（系统通知/告警）模板
 - **自定义模板** — 支持自定义模板目录，优先级高于内置模板
 - **附件支持** — 可附加任意本地文件
 - **多种加密** — 支持 `SSL`（端口 `465`）和 `STARTTLS`（端口 `587`）
 - **完整 MIME** — 纯文本、`HTML`、多收件人（`To/CC/BCC`）、`Reply-To` 等
 
 ## 安装
 
 ```bash
 pip install maillite
 ```
 
 ## 快速开始
 
 ### 发送纯文本邮件
 
 ```python
 from maillite import EasyMailer
 
 mailer = EasyMailer(
     host="smtp.qq.com",
     port=465,
     username="your@qq.com",
     password="your_auth_code",   # QQ 邮箱请使用授权码
     use_ssl=True,
 )
 
 mailer.send(
     to="test@qq.com",
     subject="测试邮件",
     body="这是一封来自 MailLite 的测试邮件。",
 )
 ```
 
 ### 使用模板发送邮件
 
 ```python
 mailer.send_template(
     to="test@qq.com",
     subject="欢迎 {{ name }}",
     template_name="welcome",
     context={
         "name": "张三",
         "title": "欢迎加入",
         "message": "感谢您的注册！",
         "action_url": "https://example.com/dashboard",
         "action_text": "进入控制台",
     },
 )
 ```
 
 ### 发送服务异常告警
 
 ```python
 import traceback
 
 mailer.send_template(
     to="test@qq.com",
     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="test@qq.com",
     subject="【{{ severity }}】{{ service_name }} 服务异常",
     template_name="admonition",
     context={
         "name": "运维同学",
         "severity": "严重",
         "service_name": "API Gateway",
         "code": "ERR_502",
         "message": traceback.format_exc(),
     },
 )
 ```
 
 ## 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）**
 
 ```python
 attachments=["d:/report.pdf", "d:/data.xlsx"]
 ```
 
 **2. 二进制数据（dict）** — 适用于动态生成的图片、文件等
 
 ```python
 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 按钮文案 | `"立即查看"` |
 | `team_name` | 团队署名 | `"MailLite 团队"` |
 | `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` | 按钮文案 | `"查看详情"` |
 | `team_name` | 团队署名 | `"MailLite 监控团队"` |
 | `help_url` | 底部帮助链接 | — |
 
 > `severity` 支持以下值：`"严重"` / `"critical"` (红色)、`"警告"` / `"warning"` (橙色)、`"成功"` / `"success"` (绿色)、`"信息"` / `"info"` (蓝色)，其他值默认蓝色。
 
 ## 自定义模板
 
 创建自己的模板目录并放置 `.html` / `.txt` 文件：
 
 ```
 my_templates/
 ├── invoice.html
 └── invoice.txt
 ```
 
 ```python
 mailer = EasyMailer(
     host="smtp.qq.com",
     port=465,
     username="your@qq.com",
     password="your_auth_code",
     use_ssl=True,
     template_dir="./my_templates",   # 自定义模板目录
 )
 
 mailer.send_template(
     to="test@qq.com",
     subject="发票 #{{ invoice_no }}",
     template_name="invoice",
     context={"invoice_no": "20260708-001", "amount": "¥1,280.00"},
 )
 ```
 
 > 自定义目录优先级高于内置模板。如果同名模板存在于两个目录，自定义版本会被使用。也可以在运行时通过 `mailer._template_engine.add_template_dir(path)` 动态添加模板目录。
 
 
 
Requires-Dist: jinja2>=3.0
