发送 API

Assiah 提供三种邮件发送方式：玩家邮件、系统邮件和群发邮件。所有方法返回 CompletableFuture。

方法一览

方法	返回值	说明
`sendMail(request: SendMailRequest)`	`CompletableFuture<SendResult>`	发送玩家邮件
`sendSystemMail(request: SendMailRequest)`	`CompletableFuture<SendResult>`	发送系统邮件
`broadcastMail(request: BroadcastMailRequest)`	`CompletableFuture<BroadcastResult>`	群发邮件

SendMailRequest

字段	类型	必填	说明
`sender`	`SenderSnapshot`	✅	发送者快照
`recipient`	`Recipient`	✅	收件人信息
`title`	`String`	✅	邮件标题
`body`	`String`	✅	邮件正文
`attachments`	`List<MailAttachment>`	❌	附件列表，默认为空
`sourceServer`	`String?`	❌	源服务器名称，跨服场景使用
`targetServer`	`String?`	❌	目标服务器名称，默认取收件人所在服务器
`summary`	`String?`	❌	邮件摘要，`null` 时由系统自动截取生成
`expireAt`	`Long?`	❌	过期时间戳（毫秒），`null` 表示永不过期
`relationType`	`RelationType`	❌	邮件关系类型，默认 `NONE`
`rootMailId`	`String?`	❌	会话根邮件 ID，用于回复/转发链追踪
`parentMailId`	`String?`	❌	父邮件 ID，用于回复/转发链追踪
`bypassRateLimit`	`Boolean`	❌	是否跳过发送者速率限制，默认 `false`
`receiveCondition`	`String?`	❌	Kether 接收条件脚本，仅系统/管理员邮件有效
`claimCondition`	`String?`	❌	Kether 领取条件脚本，仅系统/管理员邮件有效
`claimConditionMessage`	`String?`	❌	领取条件不满足时的自定义提示消息

SenderSnapshot

发送者快照，记录发送时的发送者信息：

字段	类型	说明
`type`	`SourceType`	发送来源类型（`PLAYER` / `ADMIN` / `SYSTEM`）
`uniqueId`	`UUID?`	发送者 UUID，系统邮件时为 `null`
`name`	`String`	发送者标识名称
`displayName`	`String`	发送者显示名称，默认与 `name` 相同

提供工厂方法快速创建：

SenderSnapshot.player(uuid, "Steve")           // 玩家
SenderSnapshot.admin(uuid, "Admin")            // 管理员
SenderSnapshot.system()                         // 系统（默认名称）
SenderSnapshot.system("custom", "自定义系统")   // 系统（自定义名称）

Recipient

收件人定位对象：

字段	类型	说明
`uuid`	`UUID`	收件人 UUID
`name`	`String`	收件人玩家名称
`server`	`String?`	当前所在服务器名称
`online`	`Boolean`	是否在线，默认 `false`
`proxyNode`	`String?`	代理节点名称，用于 BungeeCord 跨服路由

BroadcastMailRequest

字段	类型	必填	说明
`sender`	`SenderSnapshot`	✅	发送者快照
`recipients`	`List<Recipient>`	✅	收件人列表
`title`	`String`	✅	邮件标题
`body`	`String`	✅	邮件正文
`attachments`	`List<MailAttachment>`	❌	附件列表，默认为空
`sourceServer`	`String?`	❌	源服务器名称
`summary`	`String?`	❌	邮件摘要
`expireAt`	`Long?`	❌	过期时间戳
`receiveCondition`	`String?`	❌	Kether 接收条件脚本
`claimCondition`	`String?`	❌	Kether 领取条件脚本
`claimConditionMessage`	`String?`	❌	领取条件不满足时的提示消息

返回类型

SendResult

字段	类型	说明
`success`	`Boolean`	是否发送成功
`mailId`	`String?`	邮件 ID（成功时返回）
`createdAt`	`Long?`	邮件创建时间戳（成功时返回）
`failure`	`MailFailure?`	失败信息（失败时返回）

MailFailure

字段	类型	说明
`code`	`String`	错误码（如 `"MAIL_NOT_FOUND"`、`"ALREADY_CLAIMED"`）
`message`	`String`	人类可读的错误描述

BroadcastResult

字段	类型	说明
`total`	`Int`	目标收件人总数
`successCount`	`Int`	发送成功数量
`failureCount`	`Int`	发送失败数量
`failures`	`List<BroadcastFailure>`	失败详情列表
`filteredCount`	`Int`	因接收条件不满足而被过滤的数量
`filteredRecipients`	`List<UUID>`	被过滤的收件人 UUID 列表

BroadcastFailure 包含 recipientName: String 和 failure: MailFailure。

附件类型

所有附件类型位于 kim.hhhhhy.assiah.api.mail 包下，实现 MailAttachment 密封接口。

ItemAttachment

物品附件，附带实际 ItemStack：

import kim.hhhhhy.assiah.api.mail.ItemAttachment

val attachment = ItemAttachment(
    item = itemStack
)

SourceItemAttachment

物品库物品附件，领取时根据物品源动态构建：

import kim.hhhhhy.assiah.api.mail.SourceItemAttachment

val attachment = SourceItemAttachment(
    sourceId = "mythicmobs:FireSword",
    amount = 3
)

TextAttachment

纯文本附件（默认不可领取）：

import kim.hhhhhy.assiah.api.mail.TextAttachment

val attachment = TextAttachment(
    text = "这是一段附件文本"
)

KetherAttachment

Kether 脚本附件，领取时执行脚本：

import kim.hhhhhy.assiah.api.mail.KetherAttachment

val attachment = KetherAttachment(
    script = "tell sender *&\"恭喜领取成功！\""
)

CurrencyAttachment

货币附件：

import kim.hhhhhy.assiah.api.mail.CurrencyAttachment

val attachment = CurrencyAttachment(
    currencyKey = "vault",
    amount = 1000.0
)

使用示例

构造器方式

import kim.hhhhhy.assiah.api.AssiahAPI
import kim.hhhhhy.assiah.api.request.SendMailRequest
import kim.hhhhhy.assiah.api.mail.SenderSnapshot
import kim.hhhhhy.assiah.api.mail.Recipient
import kim.hhhhhy.assiah.api.mail.ItemAttachment

// 发送玩家邮件
val request = SendMailRequest(
    sender = SenderSnapshot.player(senderUUID, "Steve"),
    recipient = Recipient(receiverUUID, "Alex"),
    title = "交易物品",
    body = "这是你购买的物品，请查收。",
    attachments = listOf(
        ItemAttachment(item = diamondSword)
    )
)

AssiahAPI.sendMail(request).thenAccept { result ->
    if (result.success) {
        println("邮件发送成功，ID: ${result.mailId}")
    } else {
        println("发送失败: ${result.failure?.message}")
    }
}

DSL 方式

import kim.hhhhhy.assiah.api.AssiahAPI
import kim.hhhhhy.assiah.api.dsl.*

// 发送玩家邮件
AssiahAPI.sendMail {
    sender = SenderSnapshot.player(senderUUID, "Steve")
    recipient = Recipient(receiverUUID, "Alex")
    title = "交易物品"
    body = "这是你购买的物品，请查收。"
    attachment(ItemAttachment(item = diamondSword))
}

// 发送系统邮件（自动填充系统发送者）
AssiahAPI.sendSystemMail {
    recipient = Recipient(playerUUID, "Alex")
    title = "系统通知"
    body = "服务器将于今晚 22:00 维护。"
}

// 最简化系统邮件（通过 UUID + 玩家名定位收件人）
AssiahAPI.sendSystemMail(
    recipientUuid = playerUUID,
    recipientName = "Alex",
    title = "系统通知",
    body = "你的背包已满"
)

// 群发邮件
AssiahAPI.broadcastMail {
    sender = SenderSnapshot.system()
    recipients(onlineRecipients)
    title = "全服公告"
    body = "新赛季已开启！"
    attachment(CurrencyAttachment(currencyKey = "vault", amount = 500.0))
}

提示

系统邮件与玩家邮件的区别在于：系统邮件不受黑名单限制，且在 UI 中会显示为系统来源。

方法一览​

SendMailRequest​

SenderSnapshot​

Recipient​

BroadcastMailRequest​

返回类型​

SendResult​

MailFailure​

BroadcastResult​

附件类型​

ItemAttachment​

SourceItemAttachment​

TextAttachment​

KetherAttachment​

CurrencyAttachment​

使用示例​

构造器方式​

DSL 方式​