
文档 · Discord · 源代码和问题反馈
包裹、交易与奖励,尽在同一个邮箱,安全无忧
DonutMail 是一款适用于 Paper 和 Folia 的免费开源邮箱模组,支持 Minecraft 1.20.1 至 26.3。
玩家打开 /mail 命令即可看到四个标签页:收件箱 (Inbox)、包裹 (Parcels)、已发送 (Sent) 和奖励 (Rewards)。玩家可以向任何在线或离线的玩家发送物品并附带留言,或者使用货到付款 (Cash on Delivery) 进行出售:买家会看到确切的物品清单,然后选择付款或拒绝。工作人员可以通过一次活动向所有玩家发送通知,通过每日签到日历奖励登录行为并发放兑换码,控制台和其他插件也能直接将内容投递到邮箱中。
每一次领取、付款、拒绝和退回操作,在存储中都只对应一条更新记录,确保在同一台服务器上只有一个动作能成功生效。如果因崩溃导致领取中断,玩家下次上线时会完成或撤销该操作,除非你允许,否则不会有物品掉落地上。
2.0 “邮局更新” 新增了标签页式邮箱、带留言和邮费的包裹、货到付款、活动系统、每日奖励、奖励兑换码、实时及加入服务器通知、PlaceholderAPI、NuVotifier 投票奖励、Discord Webhook、邮箱方块、工作人员工具、审计日志、MySQL 网络支持以及开发者 API。此版本已在 Paper 和 Folia 1.20.1、1.21.11 和 26.3 上经过实机测试,涉及两台共享同一数据库的服务器,并作为从 1.1.0 版本的升级进行了验证。




- 四个标签页:收件箱(消息、配送、付款、退款和活动)、包裹(其他玩家发给你的物品,顶部显示货到付款)、已发送(你发出的包裹及其状态)和奖励(每日日历、每日奖励、兑换码和投票)。
- 新邮件会发光并标记为 ● New,直到你打开或领取为止。顶部的头像区域显示你的计数和每日连续登录天数。
- 左键点击以领取,或在领取前右键点击查看内部详情。
- 全部领取 (Claim All) 会领取当前标签页中符合领取条件的所有内容,你也可以在聊天栏中使用
/mail claimall 执行相同操作。
- 部分领取:符合领取条件的物品会被移交,剩余部分保留在邮箱中。物品堆叠永远不会被拆分,除非你允许,否则不会有物品掉落地上。


- 输入
/mail send <player>(或点击 Send a Parcel)打开包裹菜单。将物品放入顶部五行。
- 选择接收者:可以是任何在线或离线玩家,名称支持自动补全。可以添加最多 120 个字符的留言。
- 如果是出售,请设置货到付款价格,然后点击 Send。按钮会显示接收者、物品堆叠数、价格和邮费。
接收者会立即收到通知(在网络中的任何服务器上),或者在他们加入时收到摘要。你可以在 Sent 标签页跟踪你的包裹,并在其被领取之前撤回。无人领取的包裹将在 7 天后退回,如果在未发送的情况下关闭菜单,所有物品也会退回。
玩家可以设置谁可以向他们发送包裹(/mail block <player>,/mail toggle)。服务器可设置 10 秒冷却时间、每天 30 个包裹上限、每个邮箱最多接收来自同一发送者的 5 个包裹、每个邮箱最多 54 个包裹、物品黑名单以及可选的邮费(固定费用或按堆叠收费)。


- 向不在线的玩家出售物品:使用
/mail send Kiri cod 2.5k,或在包裹菜单中使用金粒设置价格。支持 1k、2.5m 和 1,250 等格式。
- 买家预览确切物品,查看余额变动后,选择付款并收取或拒绝。被拒绝的包裹将退回给卖家,且不会扣款。
- 款项会以付款的形式进入卖家的邮箱,如果卖家在线,他们会立即收到通知。款项会一直等待直到他们领取。
- 在资金转移之前,包裹会被锁定用于唯一的一次付款,因此双击、第二个玩家或第二台服务器都会发现它已被锁定。付款和同时进行的撤回绝不会同时成功。
- 可选税费(
cash-on-delivery.tax-percent,默认为 0)和价格限制。


/mail announce 向每位玩家发送一封邮件,包括后来加入的玩家。它只存储一次,每位玩家只需领取一次。
- 支持金钱、手中物品、代金券和控制台命令,并可设置开始时间、结束时间和权限:
/mail announce name:launch money:100 end:7d <gold>Launch week</gold> thanks for playing。
- 在线玩家会在聊天栏看到带有链接的消息;其他玩家会在收件箱中找到它。未领取的活动算作新邮件。
- 使用
/mail campaign list|end|delete|addcommand 进行管理,并为每个新活动发布可选的 Discord 帖子。
/mail give all ... 以相同方式覆盖所有已知玩家,只存储一次而不是每人一封邮件。


daily.yml 中的连续签到日历:默认为 7 天,每一天都包含物品、货币、控制台指令和优惠券。你可以添加任意多的天数。
- 当玩家在一天内首次加入时,当天的奖励会出现在 奖励 标签页中,并附带一条聊天消息用于领取。
- 日历显示已收集的天数、今天的奖励以及即将到来的奖励。
- 中断签到会重新开始(或暂停)连续签到;在最后一天之后,它会循环播放或持续发放最后一天的奖励。
- 每位玩家每天仅能领取一次奖励,跨服共享同一数据库。使用
/mail admin streak 可在服务器宕机后恢复连续签到记录。


- 玩家输入
/mail redeem <code> 或在 奖励 标签页点击 兑换代码。奖励将发送到 奖励 标签页。
- 使用
/mail code create SPRING uses:2 per-player:1 money:50 Spring reward 创建兑换码,可设置总使用次数、每位玩家的使用次数及过期时间,奖励内容可为货币、你手中的物品、优惠券或控制台指令。
- 每次兑换都会记录使用次数,并在一个事务中保存奖励。测试表明,当 10 名玩家同时尝试兑换一个仅有 3 次使用机会的兑换码时,恰好只有 3 份奖励被成功发放。
- 两次尝试之间有 3 秒的冷却时间以防止猜测。兑换码在共享同一数据库的多个服务器间通用。


- 实时通知:邮件到达时,会有标题栏提示、动作条提示、带有 [打开] 链接的聊天消息以及音效。每一项均可单独关闭。
- 加入时:展示新邮件、包裹、货到付款包裹(需支付)、奖励和公告的摘要,并提供可点击的 [打开邮箱] 按钮。
- 支付与退回:买家付款时会通知卖家;包裹退回及其原因会通知寄件人。
- 跨服同步:基于单一数据库,无论玩家当前在哪个服务器,都会收到通知。


- 每项操作仅一位获胜者。领取、支付、拒绝、收回、过期和处理人员移除等操作,在存储层均为单次条件更新。无论是双击、两名玩家还是两个服务器,绝不可能出现两人同时领取同一包裹或重复支付的情况。
- 经过测试,而非空口承诺。在存储测试中,针对 YAML、SQLite 和 MariaDB 数据库,6 到 10 个同时发起的领取、支付、拒绝、过期、收回、活动领取、每日奖励或兑换码尝试,最终每次都恰好只有一个获胜者。在实时测试中,两名玩家在同一时刻点击支付和收回操作,无论是在单服还是跨服环境下,每一轮都确保只有一位获胜者。
- 防崩溃领取。若因崩溃导致领取中断,玩家下次加入时会根据写入玩家自身存档数据(与物品写入同一 tick)的收据来自动完成或撤销该操作。
- 物品绝不会静默删除。过期的、被拒绝的、被收回的或被管理员移除的包裹会退回给寄件人;留在包裹菜单中的物品会退回给玩家或其邮箱。
- 兼容 Folia:库存变更仅在玩家所属线程上进行,不会在其他地方发生。
- 升级无忧:物品采用 Paper 的版本化格式存储,因此邮件功能可随 Minecraft 版本更新而保持兼容。
- 玩家文本保持纯文本:名称和备注永远不会添加颜色、点击事件或伪造消息。


| 占位符 |
值 |
%donutmail_unread%, %donutmail_waiting% |
新邮件数量,以及所有待处理项目总数 |
%donutmail_parcels%, %donutmail_cod% |
等待领取的包裹数量,以及需支付的货到付款包裹数量 |
%donutmail_inbox%, %donutmail_rewards%, %donutmail_campaigns% |
收件箱和奖励标签页上的邮件数量,以及尚未领取的活动邮件数量 |
%donutmail_daily_streak%, %donutmail_daily_ready% |
当前连续签到天数,以及今日奖励是否已发放 |
%donutmail_daily_next%, %donutmail_daily_next_day%, %donutmail_daily_time% |
下一个每日奖励、其对应的天数以及距离领取的时间 |
- 开发者 API:
DonutMailAPI.deliver(...) 可向收件箱或奖励标签页发送物品、货币、指令和优惠券,也支持向离线玩家和其他服务器的玩家发送:适用于宝箱、任务、商店、战斗通行证等场景。sendParcel(...) 代表玩家发送包裹,支持货到付款。还提供 createCampaign、endCampaign、unread、waiting 和 openMailbox 等方法。事件包括:MailSendEvent(可取消)、MailClaimEvent、ParcelPaidEvent、ParcelReturnedEvent、DailyRewardEvent 和 CodeRedeemEvent。
- NuVotifier:每一次投票都会转化为玩家奖励标签页上的奖励,即使玩家离线也能获得。
- Discord Webhook:新活动发布时,会将消息、奖励内容和结束时间发布到指定频道。提及(如
@everyone)永远不会触发 Ping 通知。
- 控制台命令:
/mail give <player|online|all> <hand|item|voucher|money> [message]。
- 支持 Vault 和 VaultUnlocked 经济系统,支持 SQLite、MySQL 或 MariaDB 数据库,小型服务器可使用 YAML 配置。


/mail admin view <player>:查看某玩家的待处理邮件和近期历史。右键点击可查看内容,Shift+右键点击可移除;被移除的包裹将退回给发送者。
/mail admin info:显示版本、服务器、存储、钩子和计数信息。/mail admin purge <days> 会删除已完成的邮件,而 mail.history-retention-days(默认值为 60)会自动执行此操作。
/mail admin streak <player> <days>:在停机后恢复每日连续登录奖励。
- 邮箱方块:注视一个方块(讲台、 barrels、告示牌等),然后运行
/mail admin setblock。右键点击该方块即可打开邮箱。
- 审计日志位于
plugins/DonutMail/logs/,记录每一次发送、领取、付款、退回、过期、移除、活动、兑换和每日奖励的操作。


- 在所有服务器上设置
storage.type: MYSQL,并使用相同的 MySQL 或 MariaDB 数据库。
- 在一台服务器上发送的包裹会通过实时通知到达另一台服务器上的收件人,延迟不超过
network.poll-interval-seconds(默认为 3 秒)。
- 活动和奖励代码是共享的,每位玩家的每日奖励会在所有服务器上每天发放一次。
- 跨服务器的领取和付款始终保持唯一赢家机制。
- 在两个 Paper 1.21.11 服务器共享一个 MariaDB 10.11 数据库的环境中进行了测试:包裹通过每秒轮询的方式,在 2.0 秒内到达另一台服务器并附带实时通知;“付款以防撤回”机制每轮都确保只有一个赢家。

- 替换 jar 文件并重启服务器。1.x 版本存储的邮件(YAML、SQLite 或 MySQL)仍可列出并被领取,凭证、权限和设置均保留。
- 1.x 版本中保存在
config.yml 中的文本已移至 messages.yml,同时创建 messages.yml、gui.yml 和 daily.yml。
- 实测升级:从 Paper 26.3 上的 1.1.0 版本(使用 YAML 存储,包含物品邮件、文本邮件和凭证)升级到 2.0.0 版本后,所有三种类型的邮件均可成功领取。1.1.0 版本的 SQLite 和 MySQL 表结构已通过单元测试覆盖。
- PostMaster 数据仍会被迁移,且
postmaster.* 权限继续有效。


config.yml 带有完整注释:涵盖存储和网络、包裹限制、货到付款、领取、通知、活动、代码、投票、Discord、邮箱方块、审计日志和音效。更新时会自动添加新设置,你的原有配置值将被保留。
gui.yml 包含所有菜单的配置:标题、槽位、材质、名称、描述和资源包模型。
messages.yml 包含所有聊天消息、标题和操作栏文本。可自由混合使用 MiniMessage、& 代码或 &#RRGGBB 十六进制颜色码。玩家名称和备注始终作为纯文本插入。
daily.yml 保存日历配置,vouchers/ 目录存放奖励捆绑包。
/mail reload 可在不重启服务器的情况下应用所有更改,但存储和网络设置除外。


| Server |
Minecraft |
Java |
Notes |
| Paper |
1.20.1 – 1.20.4 |
17+ |
|
| Paper |
1.20.5 – 1.21.11 |
21+ |
|
| Paper |
26.1 – 26.3 |
25+ |
|
| Folia |
1.20.1 – 26.3 |
as above |
Region-thread safe |
| Purpur, other Paper forks |
1.20.1 – 26.3 |
as above |
The same jar runs on them; they were not part of the 2.0.0 live tests. |
| Spigot, Bukkit |
— |
— |
Not supported: they lack Paper's API. The plugin says so and disables itself. |
- 金钱相关功能(货到付款、邮资、金钱奖励)需要 Vault 或 VaultUnlocked 以及一个经济插件支持。其他所有功能无需经济插件即可正常工作。
- 可选依赖:PlaceholderAPI、NuVotifier,以及用于多服务器环境的 MySQL 或 MariaDB。
- 每个版本对应一个 jar 文件。安装到服务器即可,玩家无需任何模组。
- 2.0.0 版本的现场测试在 Paper 1.20.1、1.21.11 和 26.3 以及 Folia 1.20.1、1.21.11 和 26.3 上运行,通过协议层模拟机器人进行发送、付款、拒绝和领取操作:所有检查均通过,未出现 DonutMail 错误。26.3 上的机器人通过 ViaVersion 和 ViaBackwards 使用 26.1 协议。中间版本未纳入本次测试运行。
- 第二项测试在同一 MariaDB 数据库上运行两台服务器,第三项测试将 1.1.0 数据升级至 2.0.0。

| 指令 |
功能 |
权限 |
/mail (/mailbox) |
打开邮箱 |
donutmail.use |
/mail inbox|parcels|sent|rewards |
打开选项卡 |
donutmail.use |
/mail send <player> |
向玩家发送包裹,在线或离线均可 |
donutmail.senditem |
/mail send <player> cod <price> |
货到付款的包裹 |
donutmail.senditem + donutmail.cod |
/mail claimall |
领取所有符合条件的物品 |
donutmail.use |
/mail redeem <code> |
兑换奖励码 |
donutmail.redeem |
/mail block|unblock <player>, blocklist, toggle |
谁可以向你发送包裹 |
donutmail.use |
/mail give <player|online|all> <hand|item|voucher|money> |
由管理员或控制台发放 |
donutmail.admin |
/mail announce [options] <message> |
面向所有玩家的公告活动 |
donutmail.admin |
/mail campaign list|end|delete|addcommand |
管理活动 |
donutmail.admin |
/mail code create|delete|list|addcommand |
奖励码 |
donutmail.admin |
/mail admin view|info|purge|streak|setblock|removeblock |
管理员工具 |
donutmail.admin |
/mail reload |
重新加载配置 |
donutmail.admin |
| 权限 |
默认值 |
允许的操作 |
donutmail.use |
everyone |
使用邮箱、领取物品、查看黑名单以及切换拒绝功能 |
donutmail.senditem |
everyone |
发送包裹 |
donutmail.cod |
everyone |
发送货到付款包裹 |
donutmail.redeem |
everyone |
兑换奖励码 |
donutmail.daily |
everyone |
领取每日奖励 |
donutmail.bypass.limits |
op |
忽略包裹冷却时间、每日上限和邮箱限制 |
donutmail.postage.exempt |
op |
免邮费发送包裹 |
donutmail.admin |
op |
所有管理员指令 |
/donutmail 和 /postmaster 是 /mail 的别名。1.x 版本的指令以及 PostMaster 时代的 postmaster.* 权限仍然有效。

它真的免费吗?
是的,全部免费:包括包裹、货到付款、活动、每日奖励、代码、API 以及在 MySQL 上支持多个服务器。源代码托管在 GitHub 上,采用 Apache-2.0 许可证。
我从 1.x 版本升级,会丢失任何东西吗?
不会。替换 jar 文件并重启即可。1.x 存储的邮件(YAML、SQLite 或 MySQL)、代金券、权限和设置都会保留,且 config.yml 中的 1.x 文本会移至 messages.yml。像任何更新一样,请先备份 plugins/DonutMail 目录。
它能在 Spigot 上运行吗?
不能。DonutMail 使用 Paper 的 API(Adventure 文本库、区域调度器)。Paper 可以作为 Spigot 的直接替代品。
玩家能利用它刷物品吗?
每一次领取、付款、拒绝、退回和过期都只涉及一个条件性更新,且在任何服务器上只能有一个操作胜出。如果领取过程因崩溃而中断,系统会根据玩家存档数据中的收据完成或撤销该操作。如果你发现了漏洞,请私下报告(详见 GitHub 上的 SECURITY.md)。
玩家能利用货到付款互相欺诈吗?
买家在付款前能看到确切的物品,并为预览中的内容付款。卖家在发送包裹后无法更改其内容;在款项未支付前,卖家可以撤回包裹,且付款和撤回在同一时刻不能同时成功。
没人领取的包裹会发生什么?
它们在 parcels.expire-days(7天)后退回给发送者。退回的包裹和款项永不过期。
我的服务器上另一个插件也有 /mail 命令,哪个会生效?
如果其他插件占用了 /mail,/mailbox 和 /donutmail 仍会打开 DonutMail,并且可以通过 commands.yml 中的别名将 /mail 指向那个插件。
我如何向所有玩家(包括新加入的玩家)发放物品?
使用 /mail announce。它只存储一次,每个玩家领取一次。
我该如何翻译它?
编辑 messages.yml(聊天消息)和 gui.yml(菜单),然后运行 /mail reload。MiniMessage、& 代码和十六进制颜色均支持。
文档在哪里?
在我们的网站上:Documentation · Configuration · Commands · Permissions · Placeholders · Developer API · Issues


















DonutMail 采用 Apache-2.0 许可证授权。本宣传图中使用的 Outfit 和 Inter 字体遵循 SIL Open Font License 1.1 许可协议。截图为未加修饰的 Minecraft 原版客户端在运行该插件的 Paper 服务器上的实时画面。DonutMail 是一个独立项目,与 Mojang、Microsoft 或任何为其提供灵感的服务端无关。
正在运营服务器? NightBeam 的高级插件已在 BuiltByBit 上架:NightWatch Pro 反作弊、AstralSMP 配置、Astral Core 等。
NightBeam Studio 更多作品
关注: YouTube · Instagram · X · Facebook

Docs · Discord · Source and issues
Parcels, trades and rewards in one mailbox, made safe
DonutMail is a free, open-source mailbox for Paper and Folia, from Minecraft 1.20.1 to 26.3.
Players open /mail and get four tabs: Inbox, Parcels, Sent and Rewards. They send items to any player, online or
offline, with a note, or sell them with cash on delivery: the buyer sees the exact items, then pays or declines.
Staff reach every player with one campaign, reward logins with a daily streak calendar and hand out codes, and the
console and other plugins deliver straight into the mailbox.
Every claim, payment, decline and return is one update in storage that exactly one action, on one server, can win. A
claim cut off by a crash is finished or undone the next time the player joins, and nothing is dropped on the ground
unless you allow it.
2.0 "The Post Office Update" adds the tabbed mailbox, parcels with notes and postage, cash on delivery, campaigns,
daily rewards, reward codes, live and join notifications, PlaceholderAPI, NuVotifier vote rewards, a Discord webhook,
mailbox blocks, staff tools, an audit log, MySQL networks and a developer API. This release was tested live on Paper
and Folia 1.20.1, 1.21.11 and 26.3, on two servers sharing one database, and as an upgrade from 1.1.0.




- Four tabs: Inbox (messages, deliveries, payments, returns and campaigns), Parcels (items other players sent you,
cash on delivery at the top), Sent (your parcels and what happened to them) and Rewards (the daily calendar, daily
rewards, codes and votes).
- New mail glows and is marked ● New until you open or claim it. Your head at the top shows your counts and
your daily streak.
- Left-click to claim, or right-click to look inside before you do.
- Claim All takes everything on the tab that fits, and
/mail claimall does the same from chat.
- Partial claims: what fits is handed over and the rest stays in the mailbox. Stacks are never split, and nothing
is dropped on the ground unless you allow it.


/mail send <player> (or Send a Parcel) opens the parcel menu. Put the items in the top five rows.
- Pick the recipient: any player, online or offline, and names tab-complete. Add a note of up to 120 characters.
- Set a cash-on-delivery price if you are selling, then press Send. The button shows the recipient, the stacks,
the price and the postage.
The recipient is told at once, on any server of a network, or with a summary when they join. Follow your parcels on
the Sent tab and take one back until it is claimed. Parcels nobody claims come back after 7 days, and closing
the menu without sending gives everything back.
Players choose who can send them parcels (/mail block <player>, /mail toggle). Servers set a 10-second cooldown,
30 parcels a day, 5 parcels from one sender per mailbox, 54 per mailbox, an item blacklist and optional postage (a
flat fee and/or a fee per stack).


- Sell to a player who is not online:
/mail send Kiri cod 2.5k, or set the price with the gold nugget in the parcel
menu. 1k, 2.5m and 1,250 work.
- The buyer previews the exact items, with their balance before and after, then pays and collects or
declines. A declined parcel goes back to the seller and nothing is charged.
- The money reaches the seller as a payment in their mailbox, and they are told right away if they are online.
It waits there until they collect it.
- The parcel is locked for one payment before any money moves, so a double click, a second player or a second server
finds it locked. A payment and a take-back at the same moment can never both succeed.
- Optional tax (
cash-on-delivery.tax-percent, 0 by default) and price limits.


/mail announce sends one mail to every player, including players who join later. It is stored once, and each
player claims it once.
- Money, the item in your hand, vouchers and console commands, with an optional start, end and permission:
/mail announce name:launch money:100 end:7d <gold>Launch week</gold> thanks for playing.
- Online players get a chat line with a link; everyone else finds it in their Inbox. Unclaimed campaigns count as new
mail.
/mail campaign list|end|delete|addcommand to manage them, and an optional Discord post for each new one.
/mail give all ... reaches every known player the same way, stored once instead of one mail each.


- A streak calendar in
daily.yml: 7 days by default, each with items, money, console commands and a voucher. Add as
many days as you like.
- When a player joins on a new day, that day's reward goes to the Rewards tab, with a chat line to claim it.
- The calendar shows the days collected, today's reward and what is coming.
- Missing a day starts the streak again (or just pauses it); after the last day it loops or keeps giving the last
reward.
- One delivery per player per day, also across servers on one database.
/mail admin streak restores a streak after
an outage.


- Players type
/mail redeem <code> or click Redeem a Code on the Rewards tab. The reward arrives in the Rewards
tab.
/mail code create SPRING uses:2 per-player:1 money:50 Spring reward: total uses, uses per player and an expiry,
with money, the item in your hand, a voucher or console commands.
- Each redemption counts the use and saves the reward in one transaction. In the tests, 10 players redeeming a code
with 3 uses at the same moment got exactly 3 rewards.
- A 3-second cooldown between attempts stops guessing. Codes are shared between servers on one database.


- Live: a title, an action bar line, a chat line with an [Open] link and a sound the moment mail arrives. Each
one can be turned off.
- When you join: a summary of new mail, parcels, cash-on-delivery parcels to pay, rewards and announcements, with
a clickable [Open mailbox].
- Payments and returns: sellers are told when a buyer pays, and senders when a parcel comes back and why.
- Across servers: on one database, players are told on whichever server they are on.


- One winner per action. Claiming, paying, declining, taking back, expiry and staff removal are each one
conditional update in storage. Two clicks, two players or two servers can never both take the same parcel or pay
for it twice.
- Tested, not promised. In the storage tests, 6 to 10 attempts at the same claim, payment, decline, expiry,
take-back, campaign claim, daily delivery or code redemption start at the same moment, on YAML, SQLite and MariaDB.
Exactly one wins, every time. In the live tests, a payment and a take-back clicked at the same moment by two players
had one winner in every round, on one server and across two.
- Crash-safe claims. A claim interrupted by a crash is finished or undone the next time the player joins, decided
by a receipt written into the player's own save data in the same tick as the items.
- Items are never deleted silently. Expired, declined, taken-back and staff-removed parcels go back to the sender,
and items left in the parcel menu go back to the player or their mailbox.
- Folia-safe: inventories change on the player's own thread and nowhere else.
- Upgrade-proof: items are stored in Paper's versioned format, so mail survives Minecraft updates.
- Player text stays text: names and notes can never add colors, click events or fake messages.


| Placeholder |
Value |
%donutmail_unread%, %donutmail_waiting% |
New mail, and everything waiting |
%donutmail_parcels%, %donutmail_cod% |
Parcels waiting, and cash-on-delivery parcels to pay |
%donutmail_inbox%, %donutmail_rewards%, %donutmail_campaigns% |
Mail on the Inbox and Rewards tabs, and campaigns not claimed yet |
%donutmail_daily_streak%, %donutmail_daily_ready% |
The daily streak, and whether today's reward was delivered |
%donutmail_daily_next%, %donutmail_daily_next_day%, %donutmail_daily_time% |
The next daily reward, its day and the time until it |
- Developer API:
DonutMailAPI.deliver(...) sends items, money, commands and vouchers to the Inbox or the Rewards
tab, also to offline players and players on other servers: crates, quests, shops, battle passes. sendParcel(...)
sends a parcel on a player's behalf, with cash on delivery, and there are createCampaign, endCampaign,
unread, waiting and openMailbox. Events: MailSendEvent (cancellable), MailClaimEvent, ParcelPaidEvent,
ParcelReturnedEvent, DailyRewardEvent and CodeRedeemEvent.
- NuVotifier: every vote becomes a reward on the player's Rewards tab, also when they are offline.
- Discord webhook: new campaigns are posted to a channel with the message, the rewards and the end time. Mentions
such as
@everyone are never pinged.
- The console:
/mail give <player|online|all> <hand|item|voucher|money> [message].
- Vault and VaultUnlocked economies, SQLite, MySQL or MariaDB, and YAML for small servers.


/mail admin view <player>: a player's waiting mail and recent history. Right-click to look inside,
shift-right-click to remove; a player's parcel goes back to its sender.
/mail admin info: version, server, storage, hooks and counts. /mail admin purge <days> deletes finished mail,
and mail.history-retention-days (60) does it automatically.
/mail admin streak <player> <days> restores a daily streak after an outage.
- Mailbox blocks: look at a block (a lectern, a barrel, a sign) and run
/mail admin setblock. Right-clicking it
opens the mailbox.
- An audit log in
plugins/DonutMail/logs/ has a line for every send, claim, payment, return, expiry, removal,
campaign, redemption and daily reward.


- Set
storage.type: MYSQL on every server, with the same MySQL or MariaDB database.
- A parcel sent on one server reaches its recipient on another, with a live notice, within
network.poll-interval-seconds (3 by default).
- Campaigns and reward codes are shared, and each player's daily reward is delivered once a day across all servers.
- Claims and payments stay single-winner across servers.
- Tested on two Paper 1.21.11 servers sharing one MariaDB 10.11 database: a parcel reached the other server with a
live notice after 2.0 seconds (polling every second), and pay against take-back had one winner in every round.

- Replace the jar and restart. Mail stored by 1.x (YAML, SQLite or MySQL) is listed and claimable, and vouchers,
permissions and settings are kept.
- The texts 1.x kept in
config.yml move to messages.yml, and messages.yml, gui.yml and daily.yml are
created.
- Tested live: 1.1.0 on Paper 26.3 with YAML storage, an item mail, a text mail and a voucher, then 2.0.0 swapped in
and all three claimed. The 1.1.0 SQLite and MySQL tables are covered by the unit tests.
- PostMaster data is still migrated, and the
postmaster.* permissions keep working.


config.yml is fully commented: storage and network, parcel limits, cash on delivery, claims, notifications,
campaigns, codes, votes, Discord, mailbox blocks, the audit log and sounds. New settings are added automatically
when you update; your values are kept.
gui.yml has every menu: titles, slots, materials, names, lore and resource-pack models.
messages.yml has every chat line, title and action bar text. Use MiniMessage, & codes or &#RRGGBB hex,
mixed freely. Player names and notes are always inserted as plain text.
daily.yml holds the calendar, and vouchers/ holds reward bundles.
/mail reload applies everything without a restart, except storage and network settings.


| Server |
Minecraft |
Java |
Notes |
| Paper |
1.20.1 – 1.20.4 |
17+ |
|
| Paper |
1.20.5 – 1.21.11 |
21+ |
|
| Paper |
26.1 – 26.3 |
25+ |
|
| Folia |
1.20.1 – 26.3 |
as above |
Region-thread safe |
| Purpur, other Paper forks |
1.20.1 – 26.3 |
as above |
The same jar runs on them; they were not part of the 2.0.0 live tests. |
| Spigot, Bukkit |
— |
— |
Not supported: they lack Paper's API. The plugin says so and disables itself. |
- Money features (cash on delivery, postage, money rewards) need Vault or VaultUnlocked and an economy plugin.
Everything else works without one.
- Optional: PlaceholderAPI, NuVotifier, and MySQL or MariaDB for several servers.
- One jar for every version. Install it on the server; players need no mods.
- The 2.0.0 live tests ran on Paper 1.20.1, 1.21.11 and 26.3 and Folia 1.20.1, 1.21.11 and 26.3, with bots over the
network protocol sending, paying, declining and claiming on each: every check passed, with no DonutMail errors.
Bots on 26.3 used the 26.1 protocol through ViaVersion and ViaBackwards. Versions in between were not part of the
run.
- A second test runs two servers on one MariaDB database, and a third upgrades 1.1.0 data to 2.0.0.

| Command |
What it does |
Permission |
/mail (/mailbox) |
Open the mailbox |
donutmail.use |
/mail inbox|parcels|sent|rewards |
Open a tab |
donutmail.use |
/mail send <player> |
Send a parcel to a player, online or offline |
donutmail.senditem |
/mail send <player> cod <price> |
A parcel with cash on delivery |
donutmail.senditem + donutmail.cod |
/mail claimall |
Claim everything that fits |
donutmail.use |
/mail redeem <code> |
Redeem a reward code |
donutmail.redeem |
/mail block|unblock <player>, blocklist, toggle |
Who can send you parcels |
donutmail.use |
/mail give <player|online|all> <hand|item|voucher|money> |
Deliver from staff or the console |
donutmail.admin |
/mail announce [options] <message> |
A campaign for every player |
donutmail.admin |
/mail campaign list|end|delete|addcommand |
Manage campaigns |
donutmail.admin |
/mail code create|delete|list|addcommand |
Reward codes |
donutmail.admin |
/mail admin view|info|purge|streak|setblock|removeblock |
Staff tools |
donutmail.admin |
/mail reload |
Reload the configuration |
donutmail.admin |
| Permission |
Default |
What it allows |
donutmail.use |
everyone |
The mailbox, claiming, the block list and the refuse toggle |
donutmail.senditem |
everyone |
Send parcels |
donutmail.cod |
everyone |
Send cash-on-delivery parcels |
donutmail.redeem |
everyone |
Redeem reward codes |
donutmail.daily |
everyone |
Receive daily rewards |
donutmail.bypass.limits |
op |
Ignore the parcel cooldown, the daily limit and the mailbox limits |
donutmail.postage.exempt |
op |
Send parcels without postage |
donutmail.admin |
op |
Every staff command |
/donutmail and /postmaster are aliases of /mail. The 1.x commands and the PostMaster-era postmaster.*
permissions keep working.

Is it really free?
Yes, all of it: parcels, cash on delivery, campaigns, daily rewards, codes, the API and several servers on MySQL. The
source is on GitHub under Apache-2.0.
I'm updating from 1.x. Will I lose anything?
No. Replace the jar and restart. Mail stored by 1.x (YAML, SQLite or MySQL), vouchers, permissions and settings are
kept, and the 1.x texts in config.yml move to messages.yml. Back up plugins/DonutMail beforehand, as with any
update.
Does it work on Spigot?
No. DonutMail uses Paper's API (Adventure text, region schedulers). Paper is a drop-in replacement for Spigot.
Can players dupe items with it?
Every claim, payment, decline, return and expiry is one conditional update that exactly one action can win, also
across servers, and a claim interrupted by a crash is finished or undone from a receipt in the player's own save
data. If you ever find a way, please report it privately (see SECURITY.md on GitHub).
Can players scam each other with cash on delivery?
The buyer sees the exact items before paying, and pays for exactly what is in the preview. The seller cannot change a
parcel after sending it; they can take it back while it is unpaid, and a payment and a take-back at the same moment
cannot both succeed.
What happens to parcels nobody claims?
They go back to the sender after parcels.expire-days (7). Returned parcels and payments never expire.
Another plugin on my server also has a /mail command. Which one runs?
If another plugin takes /mail, /mailbox and /donutmail still open DonutMail, and an alias in commands.yml can
point /mail at it.
How do I give something to every player, including new ones?
/mail announce. It is stored once and each player claims it once.
How do I translate it?
Edit messages.yml (chat) and gui.yml (menus) and run /mail reload. MiniMessage, & codes and hex colors all
work.
Where are the docs?
On our website: Documentation · Configuration · Commands · Permissions · Placeholders · Developer API · Issues


















DonutMail is licensed under Apache-2.0. The Outfit and Inter fonts used in this artwork are licensed under the SIL
Open Font License 1.1. Screenshots are unedited captures of the vanilla Minecraft client on a Paper server running
the plugin. DonutMail is an independent project and is not affiliated with Mojang, Microsoft or any server it takes
inspiration from.
Running a server? NightBeam's premium plugins are on BuiltByBit: NightWatch Pro anti-cheat, the AstralSMP setup, Astral Core and more.
More from NightBeam Studio
Follow: YouTube · Instagram · X · Facebook
评论 0
登录后参与评分
还没有评论,来抢沙发吧