开发者 API

Assiah 提供完整的 API 供其他插件集成邮箱功能。所有 API 通过 AssiahAPI 单例对象调用，返回 CompletableFuture 异步结果。

面向开发者

本页面面向插件开发者。如果你是服主，可以跳过此页。

引入依赖

// build.gradle.kts
repositories {
    // Assiah 发布仓库（或本地 libs 目录）
}

dependencies {
    compileOnly(fileTree("libs") { include("Assiah-*.jar") })
}

核心入口

import kim.hhhhhy.assiah.api.AssiahAPI

AssiahAPI 是所有公开 API 的唯一入口。插件启动后即可调用，无需手动初始化。

发送邮件

基础方式（构建 Request）

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

val request = SendMailRequest(
    sender = SenderSnapshot.player(uuid, "Steve"),
    recipient = Recipient(targetUuid, "Alex"),
    title = "你好",
    body = "这是一封测试邮件"
)

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

DSL 参数展开

import kim.hhhhhy.assiah.api.dsl.sendMail

AssiahAPI.sendMail(
    sender = SenderSnapshot.player(uuid, "Steve"),
    recipient = Recipient(targetUuid, "Alex"),
    title = "你好",
    body = "这是一封测试邮件"
)

DSL 构建器

import kim.hhhhhy.assiah.api.dsl.sendMail

AssiahAPI.sendMail {
    sender = SenderSnapshot.player(uuid, "Steve")
    recipient = Recipient(targetUuid, "Alex")
    title = "你好"
    body = "这是一封测试邮件"
    attachment(ItemAttachment(itemStack))
    expireAt = System.currentTimeMillis() + 86400000L  // 24 小时后过期
}

发送系统邮件

系统邮件的发送者类型为系统，可能绕过部分用户偏好限制。

DSL 参数展开

import kim.hhhhhy.assiah.api.dsl.sendSystemMail

// 通过 Recipient 对象
AssiahAPI.sendSystemMail(
    recipient = Recipient(targetUuid, "Alex"),
    title = "系统通知",
    body = "你的背包已满"
)

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

DSL 构建器

import kim.hhhhhy.assiah.api.dsl.sendSystemMail

AssiahAPI.sendSystemMail {
    recipient = Recipient(targetUuid, "Alex")
    title = "系统通知"
    body = "你的背包已满"
    attachment(ItemAttachment(itemStack))
}

快捷发送单附件邮件

快捷发送 API 复用 /assiah send 背后的默认邮件构造逻辑。调用方只需要提供发送者、收件人和单个附件；标题、正文、附件显示名留空时，会自动读取 mailbox.yml -> command-send 中对应附件类型的默认文案。

可用方法

方法	适用场景
`quickSendMail(request)`	传入 `QuickSendMailRequest`，适合你已经构造好 `MailAttachment` 的场景
`quickSendItemMail(sender, recipient, item, ...)`	快速发送一个 `ItemStack` 物品附件
`quickSendTextMail(sender, recipient, text, ...)`	快速发送一份文本附件
`quickSendKetherMail(sender, recipient, script, ...)`	快速发送一个 Kether 脚本附件
`quickSendCurrencyMail(sender, recipient, currencyKey, amount, ...)`	快速发送一份货币附件
`quickSendSourceItemMail(sender, recipient, sourceId, amount = 1, ...)`	快速发送一个物品库附件，数量省略时默认为 `1`

QuickSendMailRequest 字段

字段	类型	说明
`sender`	`SenderSnapshot`	发件人快照
`recipient`	`Recipient`	收件人信息
`attachment`	`MailAttachment`	单个附件内容
`title`	`String?`	邮件标题覆盖值；为 `null` 时使用 `command-send` 默认标题
`body`	`String?`	邮件正文覆盖值；为 `null` 时使用 `command-send` 默认正文
`attachmentDisplayName`	`String?`	附件显示名覆盖值；为 `null` 时使用 `command-send` 默认附件名
`sourceServer`	`String?`	来源服务器标识
`targetServer`	`String?`	目标服务器标识，默认取 `recipient.server`
`bypassRateLimit`	`Boolean`	是否跳过发送频率限制

使用示例

import kim.hhhhhy.assiah.api.AssiahAPI
import kim.hhhhhy.assiah.api.mail.Recipient
import kim.hhhhhy.assiah.api.mail.SenderSnapshot

// 快速发放 Vault 货币附件，默认标题/正文来自 mailbox.yml -> command-send.currency
AssiahAPI.quickSendCurrencyMail(
    sender = SenderSnapshot.system(),
    recipient = Recipient(targetUuid, "Steve"),
    currencyKey = "vault",
    amount = 1000.0
)

// 快速发放物品库附件，sourceId 使用“物品源:物品ID”格式
AssiahAPI.quickSendSourceItemMail(
    sender = SenderSnapshot.system(),
    recipient = Recipient(targetUuid, "Steve"),
    sourceId = "emakiitem:starter_box",
    amount = 1
)

提示

如果你要统一调整快捷发送邮件的标题、正文或附件名称，修改配置文件详解中的 command-send 即可。

群发邮件

向多个收件人同时发送相同内容的邮件。每个收件人独立执行发送操作，单个失败不影响其他收件人。

基础方式

import kim.hhhhhy.assiah.api.AssiahAPI
import kim.hhhhhy.assiah.api.request.BroadcastMailRequest

val request = BroadcastMailRequest(
    sender = SenderSnapshot.system(),
    recipients = listOf(
        Recipient(uuid1, "Steve"),
        Recipient(uuid2, "Alex")
    ),
    title = "服务器公告",
    body = "维护通知：今晚 22:00 停服维护"
)

AssiahAPI.broadcastMail(request).thenAccept { result ->
    println("群发完成: 成功 ${result.successCount}, 失败 ${result.failureCount}")
}

DSL 构建器

import kim.hhhhhy.assiah.api.dsl.broadcastMail

AssiahAPI.broadcastMail {
    sender = SenderSnapshot.system()
    recipients(onlineRecipients)
    title = "服务器公告"
    body = "维护通知：今晚 22:00 停服维护"
    attachment(TextAttachment("详细说明"))
}

BroadcastResult

字段	类型	说明
`total`	`Int`	收件人总数
`successCount`	`Int`	发送成功数量
`failureCount`	`Int`	发送失败数量
`failures`	`List<BroadcastFailure>`	失败详情列表

每个 BroadcastFailure 包含 recipientName（收件人名称）和 failure（失败原因）。

查询邮箱

基础方式

import kim.hhhhhy.assiah.api.AssiahAPI
import kim.hhhhhy.assiah.api.request.MailboxQuery

val query = MailboxQuery(
    ownerId = playerUuid,
    page = 1,
    pageSize = 21,
    filter = MailboxFilter(folder = MailFolder.INBOX)
)

AssiahAPI.queryMailbox(query).thenAccept { page ->
    println("共 ${page.total} 封邮件，当前页 ${page.items.size} 封")
}

DSL 构建器

import kim.hhhhhy.assiah.api.dsl.queryMailbox

AssiahAPI.queryMailbox(playerUuid) {
    page = 1
    pageSize = 21
    folder = MailFolder.INBOX
    unreadOnly = true
    keywords = "公告"
}

其他 API

方法	说明	返回类型
`readMail(ownerId, mailId)`	标记邮件为已读并返回完整内容	`CompletableFuture<ReadResult>`
`claimAttachments(ownerId, mailId)`	领取邮件附件	`CompletableFuture<ClaimResult>`
`deleteMail(ownerId, mailId)`	删除邮件（移入回收站）	`CompletableFuture<DeleteResult>`
`moveMail(ownerId, mailId, folder)`	移动邮件到指定文件夹	`CompletableFuture<MoveResult>`
`replyMail(request)`	回复邮件	`CompletableFuture<SendResult>`
`forwardMail(request)`	转发邮件	`CompletableFuture<SendResult>`
`getUnreadCount(ownerId)`	获取未读邮件数量	`CompletableFuture<Long>`
`getMailThread(ownerId, mailId)`	获取邮件会话线程	`CompletableFuture<MailThread>`
`updatePreference(request)`	更新收件偏好	`CompletableFuture<PreferenceResult>`
`blockPlayer(request)`	添加/移除黑名单	`CompletableFuture<BlockResult>`
`batchOperation(request)`	批量操作（删除/归档/标记已读等）	`CompletableFuture<BatchOperationResult>`

附件类型

在发送邮件时，可以通过 attachments 参数添加附件：

import kim.hhhhhy.assiah.api.mail.ItemAttachment
import kim.hhhhhy.assiah.api.mail.TextAttachment
import kim.hhhhhy.assiah.api.mail.KetherAttachment
import kim.hhhhhy.assiah.api.mail.CurrencyAttachment

// 物品附件
val item = ItemAttachment(itemStack, displayName = "钻石剑")

// 文本附件
val text = TextAttachment("这是一段说明文字")

// Kether 脚本附件（仅系统邮件/管理员可用）
val kether = KetherAttachment("command \"give {player} diamond 1\" as console")

// 货币附件
val currency = CurrencyAttachment(
    currencyKey = "vault",      // 对应 currency.yml 中的键名
    amount = 1000.0,
    displayName = "1000 金币"
)

Kether 自定义动作

Assiah 注册了 3 个 Kether 动作，可在其他插件的 Kether 脚本中使用：

动作	参数	说明	返回值
`mail-send`	`<收件人> <标题> <正文>`	发送系统邮件	`Boolean`
`mail-unread`	`[玩家]`	获取未读邮件数量	`Long`
`mail-has-unread`	`[玩家]`	是否有未读邮件	`Boolean`

注意事项

所有 API 返回 CompletableFuture，在异步线程执行。如需在主线程处理结果，请使用 Bukkit 调度器回调
插件未完成初始化时调用 API 会返回 API_NOT_READY 错误
群发邮件默认跳过发送者速率限制，但收件人数量受 maxBatchSendSize 配置限制
货币附件和 Kether 附件在 API 层发送时不会自动扣款/校验，需调用方自行处理

引入依赖​

核心入口​

发送邮件​

基础方式（构建 Request）​

DSL 参数展开​

DSL 构建器​

发送系统邮件​

DSL 参数展开​

DSL 构建器​

快捷发送单附件邮件​

可用方法​

QuickSendMailRequest 字段​

使用示例​

群发邮件​

基础方式​

DSL 构建器​

BroadcastResult​

查询邮箱​

基础方式​

DSL 构建器​

其他 API​

附件类型​

Kether 自定义动作​

注意事项​

引入依赖

核心入口

发送邮件

基础方式（构建 Request）

DSL 参数展开

DSL 构建器

发送系统邮件

DSL 参数展开

DSL 构建器

快捷发送单附件邮件

可用方法

QuickSendMailRequest 字段

使用示例

群发邮件

基础方式

DSL 构建器

BroadcastResult

查询邮箱

基础方式

DSL 构建器

其他 API

附件类型

Kether 自定义动作

注意事项