模板邮件

邮件模板保存在插件目录的 template/ 文件夹中。插件会递归读取该目录内所有 .yml 文件，每个文件可以定义一封邮件模板。

模板通过 id 区分，可用于管理员发送、定时自动发送和 CDK 兑换。不同模板不要使用相同的 id，否则后加载的模板会覆盖先加载的模板。

插件自带的 template/示例模板邮件.yml 会在每次重载时覆盖。需要创建邮件时，应复制该文件并使用其他文件名，不要直接修改默认示例文件。

完整结构

id: "activity_reward"
icon: "APPLE"
title: "&6活动奖励"
message:
  - "&7感谢参与本次活动。"
  - "&7请在邮件到期前领取附件。"

condition:
  - "permission:{activity.reward}"
  - "papi:{%player_level% >= 10}"

only-mail: true
expiration-time: 3600

timed-send-start-time:
  year: 2026
  month: 7
  day: 20

timed-send-end-time:
  year: 2026
  month: 7
  day: 27

need-slot: 1
items:
  - "mm5,活动奖励,1,true"

receive-commands:
  - "[console]eco give %player_name% 5000"

所有字段均为模板顶层配置。定时发送时间不是必填项；未配置完整时间区间的模板不会进入定时自动发送流程。

基础信息

id: "activity_reward"
icon: "APPLE"
title: "&6活动奖励"
message:
  - "&7感谢参与本次活动。"
  - "&7请及时领取附件。"

配置项	类型	默认值	说明
id	字符串	无	邮件模板的唯一标识，用于发送邮件和关联 CDK。
icon	字符串	APPLE	邮件在邮箱列表中显示的 Minecraft 材质名称。
title	字符串	§7无标题	邮件标题，支持使用 & 颜色代码。
message	字符串列表	空列表	邮件正文，同时作为邮件物品的 Lore 显示。

icon 会通过当前服务端的 Material 名称解析。无法识别时，邮件图标会保留为纸张，但邮件数据本身仍会创建。

收件条件

condition:
  - "permission:{activity.reward}"
  - "nopermission:{activity.reward.disabled}"
  - "papi:{%player_level% >= 10}"
  - "papi:{'%player_name%' != '测试玩家'}"

condition 中的条件必须全部成立，玩家才会收到邮件。管理员发送、API 发送、重试发送、定时自动发送和 CDK 发放邮件时都会检查这些条件。

条件格式	说明
permission:{权限节点}	玩家必须拥有指定权限。
nopermission:{权限节点}	玩家不能拥有指定权限。
papi:{表达式}	解析 PlaceholderAPI 变量后，对表达式进行判断。

权限条件中的内容也会先解析 PlaceholderAPI 变量，因此权限节点可以包含玩家变量。

PAPI 表达式

使用 papi:{表达式} 时，需要安装并正常加载 PlaceholderAPI。表达式支持数值比较、字符串比较和逻辑组合。

运算符	说明	示例
>=	大于或等于	%player_level% >= 10
>	大于	%player_level% > 10
==	等于	%player_level% == 10
!=	不等于	%player_level% != 10
<	小于	%player_level% < 10
<=	小于或等于	%player_level% <= 10
&&	两侧条件同时成立	%player_level% >= 10 && %player_level% <= 20
||	两侧任意条件成立	%player_level% < 10 || %player_level% > 20

数值内容支持 +、-、*、/ 和圆括号运算。

condition:
  - "papi:{(%player_level% + 5) >= 20}"

比较字符串时，两侧字符串需要使用成对的单引号或双引号。YAML 外层引号与表达式内层引号应错开。

condition:
  - "papi:{'%player_name%' == '离渊'}"

条件不成立时，本次发送会直接停止，不会在玩家邮箱中创建邮件。通过 CDK 兑换邮件时，CDK 的兑换状态仍可能已经记录，因此应确保 CDK 关联模板的条件不会阻止目标玩家收件。

唯一邮件

only-mail: true

配置项	类型	默认值	说明
only-mail	布尔值	false	是否限制玩家永久只能收到一次该模板邮件。

启用后，只要玩家曾经成功收到过该模板，插件就会记录其模板 id。即使玩家已经领取、删除或等待邮件过期，也不能再次收到相同 id 的邮件。

该限制根据模板 id 的历史收件记录判断，不是根据玩家邮箱中当前是否存在该邮件判断。

定时自动发送本身也只会向没有该模板收件记录的玩家发送一次。对于活动、补偿或一次性奖励，建议同时启用 only-mail，避免管理员或其他调用方式重复发送。

过期时间

expiration-time: 3600

配置项	类型	默认值	单位	说明
expiration-time	整数	3600	秒	普通发送后，邮件可以保留的时间。

当邮件发送时间不在有效的定时区间内时，到期时间按以下方式计算：

邮件到期时间 = 实际收件时间 + expiration-time

常用时间换算：

时长	秒数
1 小时	3600
1 天	86400
1 周	604800

到期邮件会从玩家邮箱中删除。插件会按 config.yml 中的扫描间隔检查在线玩家，玩家切换世界时也会触发一次过期检查。

定时自动发送

定时发送需要同时配置完整的开始日期和结束日期。

timed-send-start-time:
  year: 2026
  month: 7
  day: 20

timed-send-end-time:
  year: 2026
  month: 7
  day: 27

配置项	说明
timed-send-start-time.year	自动发送开始年份。
timed-send-start-time.month	自动发送开始月份。
timed-send-start-time.day	自动发送开始日期。
timed-send-end-time.year	自动发送结束年份。
timed-send-end-time.month	自动发送结束月份。
timed-send-end-time.day	自动发送结束日期。

开始和结束时间都会被解析为对应日期的 00:00:00，使用服务器所在时区。

在有效时间区间内，插件会按照 config.yml 中的 auto-send-time 间隔扫描在线玩家。符合以下条件时，玩家会收到邮件：

• 当前时间处于开始时间与结束时间之间。
• 玩家数据已经加载完成。
• 玩家从未成功收到过该模板 id。
• 模板内所有 condition 条件均成立。

玩家在前几次扫描时条件不成立，不会产生收件记录。只要活动尚未结束，后续扫描时条件变为成立，仍可以收到邮件。

在定时区间内成功发送的邮件不会使用 expiration-time，而是直接将 timed-send-end-time 设为到期时间。因此，越晚收到邮件，可领取时间越短。

超过结束时间后，插件不再自动尝试发送该模板。管理员或 API 在定时区间外手动发送时，邮件会重新使用 expiration-time 计算到期时间。

背包空位要求

need-slot: 1

配置项	类型	默认值	说明
need-slot	整数	0	领取邮件前要求玩家主背包拥有的空槽位数量。

插件只检查玩家主背包前 36 个槽位中的完全空槽位，不会根据现有物品是否可以继续堆叠计算空间。

当空槽位不足时，邮件不会删除、附件不会发放、领取指令也不会执行。玩家可以整理背包后再次领取。

need-slot 由模板作者自行设置，插件不会根据 items 数量自动计算所需空位。

附件物品

items:
  - "mm,邮件奖励,1,true"
  - "mm5,高级奖励,2,true"
  - "ni,展示物品,1,false"

每项附件使用四段英文逗号分隔：

物品库标识,物品 ID,数量,是否给予

位置	类型	说明
第 1 段	字符串	调用的物品库标识。
第 2 段	字符串	物品在对应物品库中的 ID。
第 3 段	整数	展示或发放的物品数量。
第 4 段	布尔值	true 表示领取时给予，false 表示只展示。

附件必须完整填写四段内容。物品 ID 本身不要包含英文逗号。

物品库标识

标识	对应物品来源
mm	MythicMobs 旧版物品库。
mm5	MythicMobs 5.x 物品库。
ni	NeigeItems。
si	SX-Item。
af	AzureFlow。
oa	Oraxen。
sx	SXAttribute 物品。

使用某个标识前，服务器必须安装并正常加载对应的物品插件，并确保填写的物品 ID 存在。

false 只会阻止领取时实际给予物品，不会阻止物品出现在附件预览区域。例如：

items:
  - "mm5,稀有奖励预览,1,false"

邮箱界面的附件预览区域最多显示前 17 项附件。领取时会按配置顺序处理 items 中的全部项目，不受 17 项预览数量限制。

预览物品数量超过对应物品的最大堆叠数量时，界面中的预览数量会被限制到该物品的最大堆叠数量。实际发放流程会使用配置的数量。

领取指令

receive-commands:
  - "[console]eco give %player_name% 5000"
  - "[op]reward give %player_name% activity"
  - "spawn"

玩家点击领取按钮并通过空槽位检查后，插件会先处理附件物品，再执行 receive-commands。完成领取流程后，邮件会从该玩家邮箱中删除。

写法	执行身份	说明
[console]指令	控制台	删除 [console] 后由控制台执行。
[op]指令	临时 OP 玩家	玩家执行期间临时获得 OP，执行后恢复原状态。
无前缀指令	玩家	直接以领取邮件的玩家身份执行。

指令内容不要以 / 开头。

领取指令会先解析 PlaceholderAPI 变量，可以使用 %player_name% 等已安装扩展提供的变量。

[op] 和 [console] 是根据指令中是否包含对应文本判断的。为避免误判，应只将执行前缀写在指令开头。

插件代码不会专门处理 [player] 前缀。需要以玩家身份执行时，直接填写不带前缀的指令。

字段默认值

配置项	默认值
icon	APPLE
title	§7无标题
message	空列表
condition	空列表
only-mail	false
expiration-time	3600
need-slot	0
items	空列表
receive-commands	空列表

id 没有有效默认值，每个可用模板都应明确填写。定时发送开始时间和结束时间也没有常规默认日期，需要自动发送时必须完整配置。

重载规则

执行插件重载后，插件会重新读取 template/ 目录中的全部 .yml 文件，并重建内存中的模板列表。重载期间会关闭已经打开的邮箱界面。

重载只影响之后创建的新邮件。玩家邮箱中已经存在的邮件会保存发送当时的标题、正文、图标、附件、领取指令和到期时间，不会因模板文件修改而同步变化。

默认示例模板会在重载时重新写入，因此正式模板应保存为新的 .yml 文件。