5.1.0 - Book Letter and Item COD Support

MailboxGUI 5.1.0

MailboxGUI 5.1.0 is a major stable update with the new Book Letter system, expanded COD item-currency support, API 5.1.0 updates, improved admin inbox tools, and Paper/Purpur 26.2.x compatibility.

Requirements

• Java 17 or newer
• Spigot/Paper/Purpur backend server
• Vault is optional, but required for money mail and Vault-money COD pricing
• Citizens is optional, used only for Post Office NPC support
• MySQL and Redis are required for MailboxGUI network mode

Compatibility

MailboxGUI 5.1.0 supports:

Spigot/Paper/Purpur 1.18.2 through 1.21.11
Spigot/Paper/Purpur 26.1.x
Spigot/Paper/Purpur 26.2.x

Important notes:

• MailboxGUI 5.1.0 is required for Paper/Purpur 26.2.x support.
• MailboxGUI 5.0.1 does not support 26.2.x sign updating correctly.
• Dynmap markers are not supported on 26.1.x or 26.2.x, but core MailboxGUI features work normally.

---

What’s New

Book Letters

MailboxGUI now includes a new Book Letter type alongside Classic Paper Letters.

Players can send Book Letters through:

/mailbox
Send Mail
Letter
Book Letter
Select Recipient

Admins can send Book Letters through:

/mailbox admin tools
Send Mail
Letter
Book Letter

Book Letter features include:

• Real Book and Quill writing flow
• Temporary protected draft book
• Sign-and-close sending
• Draft cancel support with cancel
• Logout cleanup protection
• Original hotbar item restoration
• Reply links for player-sent inbox Book Letters
• No reply links for admin/server/API Book Letters
• Back to Inbox links while reading from inbox
• Admin-safe player inbox reading through admin inbox check

When a Book Letter is taken from the inbox, inbox-only clickable actions such as Reply and Back to Inbox are removed from the carried book copy.

---

New Admin Book Letter Command

MailboxGUI 5.1.0 adds:

/mba sla <recipient[,recipient2]|allplayers|onlineplayers> '<message>' --title <title> [--from <sender>] [--delay <seconds>]

Examples:

/mba sla Rismr1 'Read page two for the message.' --title Welcome --from ICServices
/mba sla allplayers 'Server news is on the next page.' --title "Server News" --from Server
/mba sla onlineplayers 'Thanks for playing today!' --title Thanks --from VoteRewards --delay 30

Notes:

• Admin/server/API Book Letters do not include reply links.
• allplayers and onlineplayers are supported.
• Multiple specific recipients can be comma-separated.
• In network mode, onlineplayers supports network-aware online recipient handling.

---

COD Item-Currency Support

COD packages now support expanded item-currency prices.

Supported examples:

100
diamond:4,gold_nugget:2,xp:100
100,diamond:3
t:rare_sword:1,xp:250

Supported COD price types:

• Vault money
• Item currency
• XP currency
• Saved item templates
• Combined prices

For admin/API COD mail, r:<returnPlayer> controls both:

• COD payment return
• Declined COD package content return

If no return recipient is provided on admin/API COD mail, returned payments or declined contents use the existing sink behavior.

---

Package Display Updates

Package display colors were updated for clearer inbox previews and admin management.

| Package Type | Display Item |
|---|---|
| Standard Package | Shulker Box |
| COD Package Pending | Red Shulker Box |
| COD Package Accepted | Blue Shulker Box |
| Returned COD Package | Yellow Shulker Box |
| COD Item-Currency Payment | Purple Shulker Box |

---

Admin Inbox Check Improvements

The admin inbox check flow has been improved for safer mail review and management.

Book Letters

In /mba tools inbox check:

• Left-click reads a Book Letter.
• Right-click deletes a Book Letter.
• Admins do not take Book Letters from player inboxes.
• Admin-read player Book Letters hide Reply.
• Admin-read player Book Letters show Back to Player Inbox.

Packages

Package items in admin inbox check now clearly show:

Right-Click to Manage this package.

This applies to standard packages, COD packages, returned COD packages, and related package mail types.

---

API 5.1.0

MailboxGUI API 5.1.0 is available for developers.

Maven dependency:

<dependency>
    <groupId>io.github.rismr1</groupId>
    <artifactId>mailboxgui-api</artifactId>
    <version>5.1.0</version>
    <scope>provided</scope>
</dependency>

API additions include:

• Book Letter mail requests
• Book Letter delivery type
• COD item-currency payment delivery type
• COD price text in delivery events and network payloads
• Book Letter delivery events
• Item-currency COD payment delivery events

New/updated API concepts include:

BookLetterMailRequest
sendBookLetter
MailDeliveryType.BOOK_LETTER
MailDeliveryType.COD_ITEM_CURRENCY_PAYMENT
codPriceText

---

MailboxGUI-DiscBridge Compatibility

MailboxGUI-DiscBridge 1.1.0 is recommended with MailboxGUI 5.1.0.

DiscBridge 1.1.0 adds support for:

• Book Letter Discord notifications
• COD item-currency payment Discord notifications
• {price} placeholder support for MailboxGUI 5.1.0 codPriceText
• Discord message language files
• Player-selectable Discord DM language

DiscBridge remains a separate addon plugin.

---

Network Mode Validation

MailboxGUI 5.1.0 has been validated for network-mode safety with MySQL and Redis.

Validated areas include:

• Book Letter send/read/reply behavior
• Book Letter draft cleanup
• COD item-currency parsing
• COD item-currency storage
• COD accept/decline flow
• COD payment return flow
• Admin command delivery
• Delayed mail
• Cross-backend inbox access
• Network locks
• DiscBridge notification payloads
• No mail data corruption during tested flows

---

Config, Language, and Data Updates

MailboxGUI 5.1.0 includes these internal version updates:

| File/Data Type | Version |
|---|---|
| Config | 12 |
| Language files | 13 |
| Mail data | 5 |

The mail data upgrade refreshes older package mail so package, COD, XP, and item-currency package inbox items use the current preview and admin management lore.

Existing config, language, and data files should not need to be deleted. Backups are still strongly recommended before updating.

---

Update Checklist

Before updating:

1. Stop the server.
2. Back up your server.
3. Back up /plugins/MailboxGUI/.
4. Replace the old MailboxGUI jar with MailboxGUI 5.1.0.
5. If using DiscBridge, update MailboxGUI-DiscBridge to 1.1.0.
6. Start the server.
7. Check console for startup warnings.
8. Test /mailbox.
9. Test sending a Classic Letter.
10. Test sending a Book Letter.
11. Test opening received mail.
12. Test COD package flow if your server uses COD.
13. Test network mode if your server uses MySQL/Redis network mail.

---

Summary

MailboxGUI 5.1.0 adds Book Letters, expands COD item-currency support, updates API delivery payloads, improves admin inbox management, validates network-mode safety, and adds required compatibility for Paper/Purpur 26.2.x.