发送 API

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

方法一览

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

SendMailRequest

字段	类型	必填	说明
sender	UUID	✅	发送者 UUID（系统邮件可使用固定 UUID）
receiver	UUID	✅	接收者 UUID
title	String	✅	邮件标题
body	String	✅	邮件正文
attachments	List<Attachment>	❌	附件列表
expireAt	Long?	❌	过期时间戳，null 表示永不过期

BroadcastMailRequest

字段	类型	必填	说明
sender	UUID	✅	发送者 UUID
title	String	✅	邮件标题
body	String	✅	邮件正文
receivers	List<UUID>	✅	接收者列表
attachments	List<Attachment>	❌	附件列表

返回类型

SendResult

字段	类型	说明
success	Boolean	是否发送成功
mailId	String?	邮件 ID（成功时返回）
message	String?	错误信息（失败时返回）

BroadcastResult

字段	类型	说明
success	Boolean	是否全部发送成功
successCount	Int	成功发送数量
failCount	Int	失败数量
mailIds	List<String>	成功发送的邮件 ID 列表

附件类型

ItemAttachment

物品附件，附带实际 ItemStack：

import kim.hhhhhy.assiah.api.attachment.ItemAttachment

val attachment = ItemAttachment(
    item = itemStack,
    amount = 1
)

TextAttachment

纯文本附件：

import kim.hhhhhy.assiah.api.attachment.TextAttachment

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

KetherAttachment

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

import kim.hhhhhy.assiah.api.attachment.KetherAttachment

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

CurrencyAttachment

货币附件：

import kim.hhhhhy.assiah.api.attachment.CurrencyAttachment

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

使用示例

构造器方式

import kim.hhhhhy.assiah.api.AssiahAPI
import kim.hhhhhy.assiah.api.request.SendMailRequest
import kim.hhhhhy.assiah.api.attachment.ItemAttachment

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

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

DSL 方式

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

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

// 发送系统邮件
AssiahAPI.sendSystemMail {
    sender = systemUUID
    receiver = playerUUID
    title = "系统通知"
    body = "服务器将于今晚 22:00 维护。"
}

// 群发邮件
AssiahAPI.broadcastMail {
    sender = systemUUID
    receivers = onlinePlayers.map { it.uniqueId }
    title = "全服公告"
    body = "新赛季已开启！"
    attachment(CurrencyAttachment(currency = "vault", amount = 500.0))
}

提示

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