定时邮件

Assiah 1.3.0 新增了 scheduled-mail.yml，可以把每日签到、每周公告、节日补偿、子服活动奖励做成自动投递任务。插件启动时会加载这个文件，执行 /assiah reload 时也会一并重载并重启调度器。

基本规则

• 调度精度是分钟级，插件每分钟检查一次是否有任务需要触发
• 支持 cron 和 timestamps 两种模式
• 时间字符串按服务器系统时区解析
• timestamps 模式下，每个时间点只会触发一次，已经过期的时间点会自动跳过
• body-format 当前只支持 PLAIN，写其他值会回退为纯文本

文件结构

enabled: false

tasks:
  daily-reward:
    enabled: true
    schedule-mode: cron
    cron: "0 8 * * *"
    target: "*:on"
    sender:
      name: "system"
      display-name: "每日签到系统"
    title: "每日签到奖励"
    body: |
      亲爱的玩家，感谢你今天的登录！
      这是你的每日签到奖励，请查收附件。
    body-format: PLAIN
    summary: "每日签到奖励，请查收附件"
    expire-after-days: 7
    attachments:
      currencies: []
      source-items: []
      texts: []
      kether: []
      items: []
    conditions:
      receive: ""
      claim: ""
      claim-message: ""

全局开关

enabled: false

设为 false 时，整个定时邮件功能不会启动；即使 tasks 里写了任务，也不会执行。

调度模式

cron 周期任务

适合每天、每周、每月循环执行的邮件，例如：

• 每日签到奖励
• 每周维护通知
• 每周末活动提醒

schedule-mode: cron
cron: "0 8 * * *"

这里使用的是 5 段式 Cron：分 时 日 月 周。

timestamps 一次性任务

适合节日福利、开服补偿、限时活动这类固定时间点发送的场景。

schedule-mode: timestamps
timestamps:
  - "2026-10-01 10:00"
  - "2026-10-03 10:00"
  - "1767223200000"

支持两种写法：

• yyyy-MM-dd HH:mm 可读时间
• 毫秒时间戳

目标选择

target 和普通群发共用同一套解析规则：

目标格式	说明
玩家名 / UUID	发送给单个玩家
*:on	所有在线玩家
*:off	所有离线玩家
*:all	所有玩家
*:on:<子服名>	指定子服当前在线玩家
*:all:<子服名>	指定子服全部历史玩家

注意：

• *:on:<子服名> 依赖 Redis 路由同步；如果目标不是当前服且没开 Redis，会直接找不到目标
• *:all:<子服名> 通过数据库中的服务器访问记录查询，不依赖 Redis 在线状态
• *:off:<子服名> 当前不支持
• 群发任务仍然受 mailbox.yml -> limit.max-batch-send-size 限制

发件人与正文

sender:
  name: "system"
  display-name: "服务器公告"

title: "每周维护通知"
body: |
  服务器将于明天凌晨 2:00 - 4:00 进行例行维护。
  维护期间将无法登录，请提前做好准备。
body-format: PLAIN
summary: "每周维护通知"
expire-after-days: 3

说明：

• sender.name 是内部发件人标识
• sender.display-name 是玩家看到的显示名
• summary 不填时，插件会自动截取正文前 80 个字符
• expire-after-days 不填时，沿用 mailbox.yml 里的全局过期天数

附件配置

定时邮件支持五类附件：

attachments:
  currencies:
    - currency: "vault"
      amount: 100
      display-name: "100 金币"
  source-items:
    - source-id: "minecraft:diamond"
      amount: 5
      display-name: "5 颗钻石"
  texts:
    - content: "签到成功！连续签到可获得更多奖励。"
      display-name: "签到提示"
  kether:
    - script: "tell color '&a你已领取每日签到奖励！'"
      display-name: "签到脚本"
  items: []

各字段含义：

• currencies：货币附件，currency 对应 currency.yml 中定义的键名
• source-items：物品库附件，source-id 格式为 物品源:物品ID
• texts：文本附件，通常用于说明或奖励描述
• kether：领取时执行的脚本附件
• items：原始物品附件，使用 Base64 序列化结果，通常只在特殊场景下手动维护

条件系统

定时邮件同样支持接收条件和领取条件：

conditions:
  receive: ""
  claim: ""
  claim-message: ""

• receive：玩家是否能收到这封邮件
• claim：玩家是否能领取附件
• claim-message：领取条件不满足时的提示内容

这套规则和管理员在 GUI 中编辑的条件脚本是同一套逻辑。

实用示例

每日在线奖励

enabled: true

tasks:
  daily-reward:
    enabled: true
    schedule-mode: cron
    cron: "0 8 * * *"
    target: "*:on"
    sender:
      name: "system"
      display-name: "每日签到系统"
    title: "每日签到奖励"
    body: |
      亲爱的玩家，感谢你今天的登录！
      这是你的每日签到奖励，请查收附件。
    body-format: PLAIN
    expire-after-days: 7
    attachments:
      currencies:
        - currency: "vault"
          amount: 100
          display-name: "100 金币"
      source-items: []
      texts: []
      kether: []
      items: []
    conditions:
      receive: ""
      claim: ""
      claim-message: ""

指定子服活动通知

survival-event:
  enabled: true
  schedule-mode: cron
  cron: "0 14 * * 6"
  target: "*:on:survival"
  sender:
    name: "system"
    display-name: "活动系统"
  title: "生存服周末活动开始！"
  body: |
    生存服周末特别活动已经开始！
    活动期间击杀怪物可获得双倍经验。
  body-format: PLAIN
  expire-after-days: 2
  attachments:
    currencies: []
    source-items: []
    texts: []
    kether:
      - script: "tell color '&6周末活动奖励已发放！'"
        display-name: "活动通知脚本"
    items: []
  conditions:
    receive: ""
    claim: ""
    claim-message: ""

节日一次性福利

spring-festival-reward:
  enabled: true
  schedule-mode: timestamps
  timestamps:
    - "2026-01-29 10:00"
    - "2026-01-30 10:00"
  target: "*:all"
  sender:
    name: "system"
    display-name: "春节活动"
  title: "春节限时福利"
  body: |
    新春快乐！
    感谢你在春节期间陪伴我们，这是你的节日福利！
  body-format: PLAIN
  expire-after-days: 14
  attachments:
    currencies:
      - currency: "vault"
        amount: 2888
        display-name: "新春红包 2888 金币"
    source-items:
      - source-id: "minecraft:firework_rocket"
        amount: 16
        display-name: "烟花 x16"
    texts: []
    kether: []
    items: []
  conditions:
    receive: ""
    claim: ""
    claim-message: ""

使用建议

• 单服只做自动公告或奖励时，可以不开 Redis，直接用 玩家名、*:on、*:off、*:all
• 群组服要用 *:on:<子服名> 时，务必为每个子服配置唯一的 server-name 并启用 Redis
• 节日补偿建议用 timestamps，这样每个时间点只会执行一次，不容易重复发
• 人数很多的任务先检查 max-batch-send-size，避免目标过多导致整批发送被拒绝
• 修改 scheduled-mail.yml 后执行 /assiah reload，不要只改文件不重载