这页聚焦 HNMail 在运营层最有价值的一组能力：

• 模板邮件
• 模板附件
• 在线 / 离线群发
• 广播任务日志

如果你把 HNMail 当“全服奖励中心”来看，这一页就是关键。

---

模板文件放哪里

当前模板文件默认位于：

plugins/HNMail/mail-templates.yml

它和其他配置文件分工不同：

• config.yml：行为开关
• messages.yml：提示文案
• mail-templates.yml：运营内容

---

当前模板的基础结构

模板根节点是 templates。

最基础的模板通常包含：

• title
• content
• attachments（可选）

例如：

templates:
  welcome:
    title: "欢迎来到服务器"
    content:
      - "你好，{player}！"
      - "欢迎来到 {server}。"
      - "使用 /mail 可以查看你的邮箱。"

当前支持的变量

• {player}
• {sender}
• {server}

这些变量会在发送时替换成真实文本。

---

当前支持的模板附件

money

attachments:
  - type: money
    currency: gold
    amount: "100.00"

适合：

• 维护补偿
• 活动奖励
• 节日礼包

command

attachments:
  - type: command
    command: "lp user {player} parent add vip"

适合：

• 权限发放
• 称号发放
• 礼包命令

item

经典写法：

attachments:
  - type: item
    source: mythic
    item: example_sword
    amount: 1

更完整的写法也支持：

attachments:
  - type: item
    item-spec:
      source: mythic
      id: example_sword
      amount: 1

其中 item-spec 也可以写成 spec，适合后续扩展更丰富的物品解析参数。

适合：

• 统一物品库奖励
• 后台补发自定义武器 / 护甲
• 后续扩展到更复杂的物品规格描述

说明：

• 经典写法下，source / item / amount 会被转换成统一 item spec
• amount 省略时按 1 处理
• 物品解析走的是 HNMail 当前接入的 item spec 解析链，而不是模板页自己手写一套 provider 逻辑
• 来源可用性仍取决于 HNCore 统一物品库能力与当前环境已安装的物品库插件
• 如果解析结果是不支持序列化的唯一堆叠物品，模板发送会被拒绝

---

当前自带的模板示例

当前模板 key 在加载时会统一转成小写。

默认模板文件里通常会有这些例子：

• welcome
• compensation
• compensation_money
• vip_reward
• mythic_reward

它们分别适合：

• 欢迎邮件
• 普通补偿信
• 带金币附件的补偿信
• 带命令附件的权限奖励信
• 带 MythicMobs / NeigeItems 物品库附件的奖励信

---

单发模板命令

/hnmail sendtemplate <玩家> <模板>

适合：

• 单玩家补发
• 测试模板效果
• 人工确认发放

---

群发模板命令

/hnmail sendtemplateall <模板>
/hnmail sendtemplateall <模板> online

online

只发给在线玩家。

不带 online

发给玩家目录中的所有已知玩家，也就是离线全玩家群发。

这类能力很强，但也意味着你需要对模板内容和附件内容更谨慎。

---

当前群发会记录什么

群发任务现在会按批异步执行，并写入两层日志：

• broadcast_job：任务级摘要
• broadcast_item：目标级结果

任务级通常记录：

• 任务 ID
• 模板名
• 模式（在线 / 全玩家）
• 发起人
• 成功数 / 失败数 / 总数
• 状态
• 失败原因（任务级）

目标级通常记录：

• 目标玩家
• 发送状态
• 邮件 ID
• 明细原因

---

广播任务常见状态

RUNNING

任务正在后台执行。

COMPLETED

任务执行完成。

FAILED

任务整体失败。通常意味着：

• 批次处理异常
• 数据读取异常
• 某段逻辑中断

注意：

• 单个目标失败，不一定让整个任务直接 FAILED
• 更常见的是任务完成，但带有若干失败目标

---

查看广播任务

当前可以通过：

/hnmail broadcastlog
/hnmail broadcastlog list running
/hnmail broadcastlog list template welcome
/hnmail broadcastlog list completed template compensation 2
/hnmail broadcastlog <任务ID>

来查看：

• 最近任务列表
• 按状态筛选
• 按模板筛选
• 某个任务的详情与失败明细

---

使用模板群发前最重要的建议

不要在第一次接触模板时就直接做“离线全玩家补偿 + 命令附件 + 金币附件”。

最稳的顺序是：

1. 先做单发模板测试
2. 再做在线玩家群发
3. 最后再做离线全玩家群发

这样你可以先确认：

• 模板变量替换没问题
• 模板附件格式没问题
• 奖励类型没问题
• 广播日志能正常记录

---

推荐的模板命名方式

建议把模板按场景分层：

• welcome_*
• compensation_*
• festival_*
• manual_*

这样比把所有模板随便堆在一起更利于长期维护，也更适合后续在 broadcastlog 里按模板筛选排查。

---

建议联动阅读

• 想理解附件类型：看 邮件投递、附件与领取机制
• 想查看命令入口：看 命令说明
• 想看真实配置：看 config.yml 配置说明
• 想查完整 %hnmail_*% 占位符：看 PlaceholderAPI 占位符
• 遇到群发失败、模板找不到、变量不替换：看 常见问题