查询 API

Assiah 提供丰富的邮箱查询与操作方法，涵盖邮件查询、操作、偏好设置、黑名单、管理员功能和模板管理。所有方法返回 CompletableFuture。

邮箱查询

方法	返回值	说明
`queryMailbox(query: MailboxQuery)`	`CompletableFuture<MailboxPage<MailSummary>>`	分页查询邮箱
`getMail(ownerId: UUID, mailId: String)`	`CompletableFuture<Mail?>`	获取邮件详情
`getMailThread(ownerId: UUID, mailId: String)`	`CompletableFuture<MailThread>`	获取邮件会话链
`getUnreadCount(ownerId: UUID)`	`CompletableFuture<Long>`	获取未读邮件数量

分页查询

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

// 构造器方式
val query = MailboxQuery(
    ownerId = playerUUID,
    page = 1,
    pageSize = 21
)
AssiahAPI.queryMailbox(query).thenAccept { page ->
    page.items.forEach { println("${it.title} - ${it.sender}") }
}

DSL 方式

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

AssiahAPI.queryMailbox(playerUUID) {
    page = 1
    pageSize = 21
    folder = MailFolder.INBOX
    unreadOnly = true
    keywords = "公告"
}.thenAccept { page ->
    // 处理分页结果
}

获取邮件详情与会话

// 获取单封邮件
AssiahAPI.getMail(playerUUID, mailId).thenAccept { mail ->
    if (mail != null) {
        println("标题: ${mail.title}")
        println("正文: ${mail.payload.body}")
        println("附件数: ${mail.payload.attachments.size}")
    }
}

// 获取邮件会话链
AssiahAPI.getMailThread(playerUUID, mailId).thenAccept { thread ->
    println("根邮件: ${thread.rootMailId}")
    thread.mails.forEach { println("[${it.createdAt}] ${it.title}") }
}

// 获取未读数
AssiahAPI.getUnreadCount(playerUUID).thenAccept { count ->
    println("未读邮件: $count")
}

邮件操作

方法	返回值	说明
`claimMail(ownerId: UUID, mailId: String)`	`CompletableFuture<ClaimResult>`	领取邮件附件
`deleteMail(ownerId: UUID, mailId: String)`	`CompletableFuture<DeleteResult>`	删除邮件（移入回收站）
`restoreTrashMail(ownerId: UUID, mailId: String)`	`CompletableFuture<DeleteResult>`	从回收站恢复邮件
`archiveMail(ownerId: UUID, mailId: String)`	`CompletableFuture<DeleteResult>`	归档邮件
`markAsRead(ownerId: UUID, mailId: String)`	`CompletableFuture<ReadResult>`	标记为已读
`markAsUnread(ownerId: UUID, mailId: String)`	`CompletableFuture<ReadResult>`	标记为未读
`replyMail(request: ReplyMailRequest)`	`CompletableFuture<SendResult>`	回复邮件
`forwardMail(request: ForwardMailRequest)`	`CompletableFuture<SendResult>`	转发邮件
`batchOperate(request: BatchOperationRequest)`	`CompletableFuture<BatchOperationResult>`	批量操作

基础操作

val ownerId = player.uniqueId

// 领取附件
AssiahAPI.claimMail(ownerId, mailId).thenAccept { result ->
    if (result.success) player.sendMessage("附件已领取")
}

// 删除邮件（移入回收站）
AssiahAPI.deleteMail(ownerId, mailId).thenAccept { result ->
    if (result.success) println("已移入回收站，当前文件夹: ${result.folder}")
}

// 从回收站恢复
AssiahAPI.restoreTrashMail(ownerId, mailId)

// 归档
AssiahAPI.archiveMail(ownerId, mailId)

// 标记已读/未读
AssiahAPI.markAsRead(ownerId, mailId)
AssiahAPI.markAsUnread(ownerId, mailId)

回复与转发

import kim.hhhhhy.assiah.api.request.ReplyMailRequest
import kim.hhhhhy.assiah.api.request.ForwardMailRequest

// 回复邮件
val reply = ReplyMailRequest(
    ownerId = playerUUID,
    originalMailId = originalMailId,
    sender = SenderSnapshot.player(playerUUID, "Steve"),
    body = "收到，谢谢！"
)
AssiahAPI.replyMail(reply)

// 转发邮件给其他玩家
val forward = ForwardMailRequest(
    ownerId = playerUUID,
    originalMailId = mailId,
    sender = SenderSnapshot.player(playerUUID, "Steve"),
    recipient = Recipient(targetUUID, "Alex"),
    includeItemAttachments = true
)
AssiahAPI.forwardMail(forward)

批量操作

import kim.hhhhhy.assiah.api.request.BatchOperationRequest
import kim.hhhhhy.assiah.api.request.BatchOperationType

// 批量标记已读
val request = BatchOperationRequest(
    ownerId = playerUUID,
    mailIds = listOf("mail_1", "mail_2", "mail_3"),
    operation = BatchOperationType.MARK_READ
)
AssiahAPI.batchOperate(request).thenAccept { result ->
    println("成功: ${result.successCount}, 失败: ${result.failureCount}")
}

// 支持的操作类型: MARK_READ, MARK_UNREAD, DELETE, ARCHIVE, RESTORE, CLAIM

偏好设置与黑名单

方法	返回值	说明
`getPreference(ownerId: UUID)`	`CompletableFuture<MailPreference>`	获取用户偏好设置
`updatePreference(request: UpdatePreferenceRequest)`	`CompletableFuture<PreferenceResult>`	更新偏好设置
`listBlockedPlayers(ownerId: UUID)`	`CompletableFuture<List<MailBlockEntry>>`	获取黑名单列表
`blockPlayer(request: BlockPlayerRequest)`	`CompletableFuture<BlockListResult>`	拉黑玩家
`unblockPlayer(ownerId: UUID, blockedId: UUID)`	`CompletableFuture<BlockListResult>`	取消拉黑

import kim.hhhhhy.assiah.api.request.UpdatePreferenceRequest
import kim.hhhhhy.assiah.api.request.BlockPlayerRequest

// 获取偏好设置
AssiahAPI.getPreference(playerUUID).thenAccept { pref ->
    println("允许玩家邮件: ${pref.allowPlayerMail}")
}

// 更新偏好设置（部分更新，仅非 null 字段生效）
val updateRequest = UpdatePreferenceRequest(
    ownerId = playerUUID,
    allowPlayerMail = true,
    enableBlacklist = false
)
AssiahAPI.updatePreference(updateRequest)

// 黑名单管理
AssiahAPI.blockPlayer(BlockPlayerRequest(
    ownerId = playerUUID,
    blockedId = targetUUID,
    blockedName = "Alex"
))
AssiahAPI.unblockPlayer(playerUUID, targetUUID)

AssiahAPI.listBlockedPlayers(playerUUID).thenAccept { entries ->
    entries.forEach { println("已拉黑: ${it.blockedName}") }
}

管理员方法

方法	返回值	说明
`inspectMailbox(request: MailAdminInspectRequest)`	`CompletableFuture<AdminInspectResult>`	管理员审查用户邮箱
`resendMail(request: MailAdminResendRequest)`	`CompletableFuture<SendResult>`	重新发送邮件
`moveMailFolder(request: MailAdminFolderRequest)`	`CompletableFuture<DeleteResult>`	移动邮件到指定文件夹

import kim.hhhhhy.assiah.api.request.MailAdminInspectRequest
import kim.hhhhhy.assiah.api.request.MailAdminResendRequest
import kim.hhhhhy.assiah.api.request.MailAdminFolderRequest

// 管理员审查用户邮箱
val inspectRequest = MailAdminInspectRequest(
    actorId = adminUUID,
    targetOwnerId = targetUUID,
    includeRecentCount = 10
)
AssiahAPI.inspectMailbox(inspectRequest).thenAccept { result ->
    if (result.success) {
        println("邮箱快照: ${result.snapshot}")
    }
}

// 重新发送邮件（可更换收件人）
val resendRequest = MailAdminResendRequest(
    actorId = adminUUID,
    targetMailId = mailId,
    newRecipient = Recipient(newTargetUUID, "NewPlayer")
)
AssiahAPI.resendMail(resendRequest)

// 移动邮件到指定文件夹
val folderRequest = MailAdminFolderRequest(
    actorId = adminUUID,
    targetMailId = mailId,
    targetFolder = MailFolder.ARCHIVE
)
AssiahAPI.moveMailFolder(folderRequest)

模板方法

方法	返回值	说明
`saveTemplate(request: SaveTemplateRequest)`	`CompletableFuture<TemplateResult>`	从草稿保存为模板
`getTemplate(templateId: String)`	`CompletableFuture<MailTemplate?>`	获取模板详情
`queryTemplates(ownerId: UUID, page: Int, pageSize: Int)`	`CompletableFuture<MailboxPage<MailTemplate>>`	分页查询模板列表
`applyTemplate(request: ApplyTemplateRequest)`	`CompletableFuture<TemplateResult>`	将模板应用到草稿
`deleteTemplate(ownerId: UUID, templateId: String)`	`CompletableFuture<TemplateResult>`	删除模板
`renameTemplate(ownerId: UUID, templateId: String, newName: String)`	`CompletableFuture<TemplateResult>`	重命名模板

import kim.hhhhhy.assiah.api.request.SaveTemplateRequest
import kim.hhhhhy.assiah.api.request.ApplyTemplateRequest

// 从草稿保存为模板
val saveRequest = SaveTemplateRequest(
    ownerId = playerUUID,
    name = "常用通知模板",
    sourceDraftId = draftId,
    includeAttachments = false
)
AssiahAPI.saveTemplate(saveRequest).thenAccept { result ->
    if (result.success) {
        println("模板已保存: ${result.template?.templateId}")
    }
}

// 分页查询模板列表（个人 + 全局）
AssiahAPI.queryTemplates(playerUUID, page = 1, pageSize = 10).thenAccept { page ->
    page.items.forEach { println("模板: ${it.name}") }
}

// 将模板应用到草稿
val applyRequest = ApplyTemplateRequest(
    ownerId = playerUUID,
    templateId = templateId,
    targetDraftId = draftId
)
AssiahAPI.applyTemplate(applyRequest)

// 删除模板
AssiahAPI.deleteTemplate(playerUUID, templateId)

// 重命名模板
AssiahAPI.renameTemplate(playerUUID, templateId, "新模板名称")

枚举类型

MailFolder

值	说明
`INBOX`	收件箱
`SENT`	已发送
`DRAFT`	草稿箱
`ARCHIVE`	归档
`TRASH`	回收站

AttachmentType

值	说明
`TEXT`	文本附件
`ITEM`	物品附件
`KETHER`	Kether 脚本附件
`CURRENCY`	货币附件
`SOURCE_ITEM`	物品库物品附件

SourceType

值	说明
`PLAYER`	玩家发送
`SYSTEM`	系统发送
`ADMIN`	管理员发送

RelationType

值	说明
`NONE`	无关联（独立邮件）
`REPLY`	回复
`FORWARD`	转发

ClaimStatus

值	说明
`NOT_CLAIMABLE`	不可领取（无附件）
`PENDING`	待领取
`CLAIMING`	领取中
`CLAIMED`	已领取
`FAILED_RETRYABLE`	领取失败（可重试）

ReadStatus

值	说明
`UNREAD`	未读
`READ`	已读

邮箱查询​

分页查询​

DSL 方式​

获取邮件详情与会话​

邮件操作​

基础操作​

回复与转发​

批量操作​

偏好设置与黑名单​

管理员方法​

模板方法​

枚举类型​

MailFolder​

AttachmentType​

SourceType​

RelationType​

ClaimStatus​

ReadStatus​

邮箱查询

分页查询

DSL 方式

获取邮件详情与会话

邮件操作

基础操作

回复与转发

批量操作

偏好设置与黑名单

管理员方法

模板方法

枚举类型

MailFolder

AttachmentType

SourceType

RelationType

ClaimStatus

ReadStatus