MailboxGUI

MailboxGUI 5.1.1 Modrinth Changelog

Vault2.0 Custom Currency and Language Update

MailboxGUI 5.1.1 is a focused compatibility and language update for the 5.1.x release line. It improves Vault2.0 custom currency support, strengthens chat-input parsing for money/COD prompts, updates Chinese language support, and improves backup cleanup behavior. ---

Added

- Added improved Vault2.0 custom currency support for money mail and Vault-money COD amount input. - Added support for parsing formatted currency input such as: - 12 Coins - 12 Dollars - 12 <custom currency name> - $12 - 12.50 - 1,000 - Added new Hong Kong Traditional Chinese language support: zh_hk. - Added messages_zh_hk.yml. - Added language upgrade support for replacing old default zh_cn values with the new bundled translation while preserving server-owner custom edits. ---

Changed

- Updated the Simplified Chinese language file: zh_cn. - Updated active language files to:

file-version: 14

- Updated MailboxGUI API version to 5.1.1. - Updated /mba clean backup cleanup coverage so newer MailboxGUI-generated backup folders can be cleaned after the admin confirms the upgrade is working. ---

Improved

- Improved chat-input cleanup for: - Money mail input - Vault-money COD amount input - Package XP input - Typed recipient input - Book Letter draft cancel input - Admin Book Letter draft cancel input - Admin/server mail prompts - Post Office mailbox name input - Improved handling for control words such as: - cancel - off - none - 0 - Improved protection against: - Currency names added by economy providers - Legacy Minecraft color codes - Hidden formatting characters - Non-breaking spaces - Currency symbols - Comma-formatted numbers ---

Fixed

- Fixed compatibility issues where renamed Vault2.0 currencies could cause money/COD chat input prompts to reject valid values. - Fixed cases where formatted or modified chat input could make valid prompt responses fail validation. ---

Compatibility

MailboxGUI 5.1.1 keeps the same compatibility target as the 5.1.x line:

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 or newer is required for Paper/Purpur 26.2.x compatibility. - MailboxGUI 5.1.1 or newer is recommended for Vault2.0 custom currency support. - MailboxGUI-DiscBridge 1.1.1 or newer is recommended for the updated zh_cn and new zh_hk language files. ---

Recommended Tests After Updating

If your server uses Vault2.0 or custom currency names, test:

Money Mail -> 12
Money Mail -> 12 <custom currency name>
Money Mail -> cancel

Player COD Package -> 12
Player COD Package -> 12 <custom currency name>
Player COD Package -> cancel

Package XP -> 12
Package XP -> cancel

Typed recipient prompt -> cancel
Book Letter draft -> cancel
Admin Book Letter draft -> cancel

/mailbox language zh_cn
/mailbox language zh_hk
/mba clean

---

Upgrade Notes

To upgrade: 1. Stop the server. 2. Back up the full plugins/MailboxGUI/ folder. 3. Replace the old MailboxGUI jar with the 5.1.1 jar. 4. Start the server. 5. Watch the console for language/config/storage synchronization messages. 6. Test money mail, COD packages, XP packages, Book Letters, and language loading. 7. After confirming everything is working, optionally run /mba clean. You should not need to delete:

config.yml
network/config.yml
language/
data/

---

Contributor

Special thanks to nice for contributing the updated Simplified Chinese (`zh_cn`) language file and the new Hong Kong Traditional Chinese (`zh_hk`) language file.

MailboxGUI 5.1.0 Changelog

MailboxGUI 5.1.0 is a major stable update that adds Book Letters, expanded COD item-currency support, API 5.1.0 payloads, improved admin inbox tools, network-mode validation, and Paper/Purpur 26.2.x compatibility.

Important Notes

- MailboxGUI 5.1.0 is required for Paper/Purpur 26.2.x compatibility. - MailboxGUI 5.0.1 and older do not support 26.2.x sign updating correctly. - MailboxGUI-DiscBridge users should update to MailboxGUI-DiscBridge 1.1.0 or newer for full 5.1.0 notification support. - Dynmap markers are not supported on 26.1.x or 26.2.x, but core MailboxGUI features still work normally. - Back up your server and /plugins/MailboxGUI/ before updating.

Compatibility

Supported server versions:

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

New: Book Letters

MailboxGUI now supports Book Letters alongside Classic Paper Letters. Book Letter features include: - Real Book and Quill writing flow - Protected temporary draft book - Sign-and-close sending - Safe cancel support using cancel - Logout cleanup protection - Original hotbar item restoration - Reply links for player-sent inbox Book Letters - Back to Inbox links while reading from the inbox - No reply links for admin/server/API Book Letters - Inbox-only clickable actions removed when a Book Letter is taken from the inbox Player flow:

/mailbox
Send Mail
Letter
Book Letter
Select Recipient

Admin flow:

/mailbox admin tools
Send Mail
Letter
Book Letter

New Admin Book Letter Command

Added:

/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 pricing. 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. Book Letter admin inbox behavior: - 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. Package admin inbox behavior: - Package items now clearly show right-click management lore. - Standard packages, COD packages, returned COD packages, and related package mail types can be managed safely from admin inbox check.

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 or newer 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

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.

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 or newer. 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.

MailboxGUI 5.0.1 - Backend Access & Offline Admin Sends

MailboxGUI 5.0.1 adds optional command-based mailbox access and improves admin mail targeting for offline players.

Added

- Added /mailbox open and /mb open. - Opens the main MailboxGUI menu directly from command. - Disabled by default. - Useful for backend servers, Velocity networks, or servers without physical mailbox/Post Office access. - Controlled by:

mailbox:
  command-open:
    enabled: false

- Added the new permission:

mailboxgui.player.open

- Added the new admin recipient tag:

offlineplayers

- offlineplayers is supported by:

/mba sl
/mba sp
/mba scod
/mba sm

Example:

/mba sl offlineplayers 'Welcome to the server' --from ExampleServer --delay 10

Improved

- Admin mail commands can now target all known offline players without sending to currently online players. - Offline player targeting supports MailboxGUI network-aware player tracking where available. - Player help and tab completion now only show /mb open when command mailbox access is enabled and the player has permission.

Language Files

- Updated language files to file-version: 12. - Added translated messages for command mailbox access and related help menu entries.

DiscBridge Compatibility

No DiscBridge update is required for this release. MailboxGUI-DiscBridge 1.0.0 works with MailboxGUI 5.0.1. The new /mb open command does not affect DiscBridge, and the new offlineplayers recipient tag uses existing MailboxGUI delivery events that DiscBridge already supports.

Updating

You can update manually by replacing the MailboxGUI jar and restarting your server. You can also use the built-in update command:

/mba update
/mba update confirm

Then restart the server to complete the update.

Velocity / Network Setups

If you run MailboxGUI on multiple backend servers, run the update command on each backend server that has MailboxGUI installed:

/mba update
/mba update confirm

Then restart each backend server.

MailboxGUI 5.0.0 - Network Support Update

MailboxGUI 5.0.0 is a major update adding optional network support for multi-backend servers while keeping normal single-server setups fully supported.

Highlights

- Added optional MailboxGUI Network Mode for Velocity-style / multi-backend setups. - Added shared MySQL/MariaDB support for network mail data. - Added Redis-backed network sync for inbox refreshes, paper notifications, admin tools, reloads, and safety locks. - Added network-aware recipient lookup for player and admin mail. - Added /mba networkindex to help index old backend playerdata for shared network recipient lookup. - Added network-aware admin tools for registered player mailboxes and Post Office boxes. - Added server/world/status display in mailbox management while network mode is enabled. - Added Remote Server status for mailboxes and PO boxes registered on other backend servers. - Added network sync for inbox changes, admin inbox edits, mailbox removals, Post Office removals, signs, and paper notifications. - Added a new /mailbox unregister GUI with Selection Mode and Manage Personal Mailboxes. - Added player-controlled online mail sound alerts. - Added website-powered update checks and staged update commands. - Added warning that network-mode updates must be staged on each backend separately. - Added support for MailboxGUI-DiscBridge 1.0.0 network notification behavior. - Completed final 5.0.0 language/config polish.

Network Setup Notes

Network mode is optional. Single-server setups do not need Redis and can continue using normal MailboxGUI features. Network mode requires: - MySQL/MariaDB shared storage - Redis - unique server-id per backend - the same MailboxGUI version on every backend MailboxGUI should be installed on backend servers that use mail. It does not need to be installed on the Velocity proxy itself. For setup instructions, use the wiki: https://plugins.imagine-craft.net/mailboxgui/wiki/

Upgrade Notes

Before enabling network mode: 1. Back up your MailboxGUI data. 2. Keep network.enabled: false. 3. Convert storage to MySQL with /mba convert MYSQL. 4. Confirm /mba convert current shows MySQL. 5. Configure network/config.yml on each backend. 6. Start one backend first, then the rest. Storage conversion is disabled while network mode is active to protect shared mail data.

MailboxGUI 4.2.1 - Barrel Mailbox Support & Maintenance Polish

MailboxGUI 4.2.1 is a focused maintenance update that adds barrel support, improves language upgrades for older 4.x installs, adds new Notification API helpers, and improves the admin update-check workflow.

Highlights

- Added barrel support for player mailboxes. - Added barrel support for public Post Office boxes. - Player mailboxes can now use a single chest or barrel on top of the fence post. - Post Office boxes can now use a single chest or barrel as the public access container. - Signs must be attached to the front face of the chest or barrel. - Existing chest mailbox setups continue working normally. - Paper new-mail notifications work with player barrel mailboxes. - Added Notification API helpers for future integrations and addon modules. - Added /mailbox admin updatecheck and /mba updatecheck. - Improved update-check output with clearer version status and the official MailboxGUI download link. - Improved language upgrade handling for older 4.x installs so old default text can update while customized language text stays protected.

Upgrade Notes

- No mailbox data conversion is required. - Existing chest mailboxes and Post Office boxes continue working. - Existing language customizations are preserved where possible. - Servers upgrading from older 4.x versions will receive safer language text updates for newer command/help and chest/barrel setup wording.

MailboxGUI 4.2.0

MailboxGUI 4.2.0 is a quality-of-life and polish update focused on better player onboarding, safer upgrades, cleaner economy handling, improved admin tools, and updated language support.

Highlights

- Added /mailbox guide and /mb guide to help players understand personal mailboxes, public Post Office boxes, Post Office NPCs, and how to get started. - Added /mailbox check and /mb check to show new unchecked mail counts without opening the inbox. - Improved Vault/economy detection so money and COD options are hidden from GUIs when unavailable. - Added configurable money display formatting for money mail, admin money mail, COD prices, and COD return payments. - Improved COD fail-safes so COD mail stays safely dormant if Vault/economy is unavailable and becomes usable again when support returns. - Updated default mailbox sign wording for clearer personal mailbox and public Post Office access signs. - Added legacy sign compatibility and automatic handling for old default sign formats. - Added /mailbox admin convert current and /mba convert current to show the active storage mode. - Simplified storage conversion to /mailbox admin convert <YAML|SQLITE|MYSQL> and /mba convert <YAML|SQLITE|MYSQL>. - Added /mailbox admin clean and /mba clean to safely clean MailboxGUI-generated backup files after confirming upgraded data is working. - Improved backup organization under plugins/MailboxGUI/data/backups/. - Improved Citizens Post Office NPC cleanup when NPCs are removed. - Updated bundled language files and language upgrade handling for 4.2.0.

Economy & Non-Economy Improvements

- MailboxGUI now adapts more cleanly when Vault or an economy plugin is not installed. - Servers without economy support still get letters, packages, mailbox access, public Post Office boxes, and Post Office NPC support. - Money mail and COD options are hidden when unavailable instead of showing unusable GUI buttons. - COD package handling now safely pauses when economy support is missing and resumes when Vault/economy is restored.

Storage & Upgrade Safety

- Existing legacy YAML installs remain on YAML unless manually converted. - Older mail data is upgraded safely without requiring a mail wipe. - Storage conversion validates the target storage before switching. - MySQL conversion/startup safety remains protected by connection/login/table validation. - Generated backups are now better organized and can be cleaned after confirming the upgrade is working.

Notes

- Vault and a compatible economy plugin are required only for money mail and COD package payments. - Citizens, Dynmap, and PlaceholderAPI remain optional hooks. - For full commands, permissions, screenshots, setup guides, API documentation, and configuration details, visit the wiki: https://plugins.imagine-craft.net/mailboxgui/wiki/

MailboxGUI 4.1.1

MailboxGUI 4.1.1 is a polish update focused on storage conversion completeness, item template storage, command/help clarity, and language updates.

Highlights

- Added provider-backed item template storage. - Added item template support to /mba convert. - Improved storage conversion validation. - Improved MySQL table validation for all 4.1.x data. - Cleaned up admin help menu command labels. - Improved /mba sp and /mba scod help descriptions. - Updated command suggestions to prefer t:<id>:<amount> template aliases. - Updated language files to file-version 7.

Storage Conversion Polish

Item templates are now stored through the active MailboxGUI storage backend: - YAML: plugins/MailboxGUI/data/itemtemplates.yml - SQLite: mailboxgui_itemtemplates - MySQL: mailboxgui_itemtemplates The /mba convert command now includes: - Player data - Post Office data - Delayed mail data - Item template data Conversion backups now also include itemtemplates.yml.

MySQL Validation Improvements

MySQL validation now checks and creates all required MailboxGUI tables before switching storage:

mailboxgui_playerdata
mailboxgui_postoffice
mailboxgui_delayedmail
mailboxgui_itemtemplates

This helps prevent incomplete storage conversion when using MySQL.

Command & Help Menu Polish

The admin help menu now shows the shorter item-template aliases:

/mba itsave <id>
/mba itlist [page]
/mba itdelete <id>
/mba itgive <id> [player]

Package command help was also improved to better explain material items, XP, and item templates. Examples:

/mba sp <recipients> [from] <item|t:id|xp...>
/mba scod <recipients> [from] <price> [r:player] <item|t:id|xp...>

Tab suggestions now prefer the shorter template format:

t:<id>:<amount>

instead of:

template:<id>:<amount>

Language Updates

Language files were updated to file-version 7. Only the changed 4.1.1 help/menu keys were updated, and translated comments were preserved.

Upgrade Notes

Existing MailboxGUI 4.1.0 data remains compatible. If a server used item templates in 4.1.0 with SQLite or MySQL, existing standalone data/itemtemplates.yml data will be imported into the active storage backend when possible. No mailbox reset is required.

MailboxGUI 4.1.0

MailboxGUI 4.1.0 is the API and command integration update. This release focuses on giving other plugins, console automation, and server systems more ways to send and manage mail through MailboxGUI.

Highlights

- Added public MailboxGUI API for plugin integrations. - Added new admin/console sending commands: - /mba sl - /mba sp - /mba scod - /mba sm - Added item templates for command-based package sending. - Added PlaceholderAPI support with %mailboxgui_*% placeholders. - Added persistent delayed mail that survives restarts. - Added delayed mail support for YAML, SQLite, and MySQL. - Added delayed mail preservation during /mba convert. - Added typed-recipient auto-import from server playerdata. - Added COD return-recipient support with /mba scod r:<player>. - Cleaned up help menus and language files.

API & Plugin Integration

MailboxGUI now includes a public API that lets other plugins send letters, regular packages, Cash-On-Delivery packages, and money mail through MailboxGUI. The API supports multiple recipients, custom sender names, delayed delivery, full ItemStack package contents, and optional COD payment return behavior. Full API documentation will be available on the MailboxGUI wiki.

New Admin / Console Sending Commands

These commands are useful for admins, console automation, and other plugins that run commands.

/mba sl <recipients> [from] '<message>'
/mba sp <recipients> [from] <item:amount...>
/mba scod <recipients> [from] <codPrice> [r:<returnPlayer>] <item:amount...>
/mba sm <recipients> [from] <amount>

Item Templates

Item templates allow admins to save real items and send them through package commands.

/mba itemtemplate save <id>
/mba itemtemplate list
/mba itemtemplate delete <id>
/mba itemtemplate give <id> [player]

Templates preserve item metadata such as enchantments, written books, lore, custom names, CustomModelData, and custom plugin data. Example:

/mba sp Rismr1 template:starter_sword:1
/mba scod Rismr1 ServerShop 1000 r:Seller template:rare_pickaxe:1

Persistent Delayed Mail

Delayed mail now survives server shutdowns and restarts. This applies to: - Player letters - Player packages - API-created mail - Command-created mail - Admin/console delayed mail Delayed mail uses the active storage backend: - YAML - SQLite - MySQL

PlaceholderAPI

MailboxGUI now supports PlaceholderAPI when installed. Example placeholders:

%mailboxgui_has_mailbox%
%mailboxgui_inbox_total%
%mailboxgui_pending_total%
%mailboxgui_storage_type%
%mailboxgui_delayed_mail_queued%

MailboxGUI still works normally without PlaceholderAPI.

Fixes & Improvements

- Fixed admin/API COD package accept behavior. - Improved COD return handling for command and API packages. - Improved package size validation for API and command-created packages. - Improved typed-recipient handling for player and admin send flows. - Improved admin multi-recipient validation. - Improved help menu organization and paging. - Updated language files for 4.1.0.

Upgrade Notes

Existing 4.0.2 mail data remains compatible with 4.1.0. No mailbox reset is required.

MailboxGUI 4.0.2

MailboxGUI 4.0.2 is a small bug-fix and polish update focused on mailbox registration, player/admin send-mail state cleanup, and package experience behavior.

What Changed

- Player mailbox registration now works by clicking either the mailbox chest or the front sign. - Admin mailbox registration now also supports clicking either the chest or front sign. - Player mailbox registration now enforces the proper front-sign mailbox setup. - Fixed a rare issue where an admin using their normal player mailbox could sometimes have money mail behave like admin/server money mail. - Package XP can now be claimed with any click. - Older package XP mail from 4.0.1 or earlier now upgrades to the new XP claim lore safely. - Updated registration language text to explain that players can click the chest or front sign.

Compatibility Note

MailboxGUI should now be listed as supporting Spigot/Paper 1.18.2+, not plain 1.18.x. It also supports 26.1.x / 26.1.1 / 26.1.2. Dynmap marker support is still not currently supported on those 26.1 versions until Dynmap provides compatible builds.

Recommended Update

This update is recommended for all servers running MailboxGUI 4.0.0 or 4.0.1.

MailboxGUI 4.0.1

MailboxGUI 4.0.1 is a small bug-fix update focused on the floating new-mail paper icon notification system. This update is recommended for all servers running MailboxGUI 4.0.0, especially servers using the floating new-mail notification feature.

Bug Fixes

- Fixed floating new-mail paper icons not updating after an admin removes mail from a player inbox. - Fixed floating paper icons remaining above a mailbox after the mailbox is unregistered. - Added cleanup behavior for broken leftover paper icons from 4.0.0. - Fixed notification state so the paper icon is removed when no unseen mail remains. - Preserved the paper icon when more unseen mail still exists in the player inbox. - Updated the floating paper icon so it is only visible to the mailbox owner.

New-Mail Paper Icon Behavior

- When a player receives mail, the icon appears above their registered mailbox. - When the player checks their inbox, the icon clears normally. - When an admin removes unread mail, the icon updates correctly. - When a mailbox is unregistered, the icon above that physical mailbox is removed. - If 4.0.0 left behind broken floating paper icons, 4.0.1 will clean them up as chunks load or during notification refresh. - Other players no longer see someone else’s floating paper notification.

Upgrade Notes

If you are updating from 4.0.0, this should be a straightforward drop-in update. Recommended steps: 1. Stop the server. 2. Back up your plugins/MailboxGUI/ folder. 3. Replace the old jar with the 4.0.1 jar. 4. Start the server. 5. Confirm old floating paper icons are cleaned up. 6. Confirm new mail notifications appear only for the mailbox owner.

Compatibility

- Supports Spigot/Paper 1.18.2 through 1.21.11. - Supports 26.1.x, 26.1.1, and 26.1.2. - Dynmap marker support is still not currently supported on 26.1.x / 26.1.1 / 26.1.2 until Dynmap provides compatible builds. - MailboxGUI itself continues to work normally without Dynmap on those versions.

MailboxGUI 4.0.0

MailboxGUI 4.0.0 is a major backend and polish update focused on safer upgrades, new storage support, cleaner mail lore, better recipient selection, and long-term plugin stability.

Highlights

- Added YAML, SQLite, and MySQL storage support. - Fresh installs now default to SQLite. - Existing installs with old YAML data from 3.1.2 or older safely stay on YAML during upgrade. - Added storage conversion commands for YAML, SQLite, and MySQL. - Added MySQL connection validation and fallback safety. - Added safer legacy data migration into the new 4.0.0 data structure. - Updated old mail upgrade handling so previous letters, packages, COD packages, and money mail stay usable. - Added one shared startup conversion timestamp for old mail that did not previously have timestamps.

Storage

- Added new storage layout under plugins/MailboxGUI/data/. - Added SQLite database support for fresh installs. - Added MySQL support for servers that want an external database. - Added conversion backups before storage conversions. - Added config update protection so failed MySQL conversions do not switch the plugin to MySQL. - Added startup fallback so failed MySQL connections fall back to SQLite instead of breaking the plugin.

Mail & GUI Polish

- Updated lore formatting for letters, packages, COD packages, returned packages, money mail, and admin mail. - Updated recipient menus to default to Online Players. - Updated recipient filter order to Online Players -> All Players -> Offline Players. - Updated Type Player Name so it searches all stored MailboxGUI players. - Updated typed player search to be case-insensitive. - Added new chat mail notification options for simple, advanced, or disabled offline summaries. - Added online delivery notification toggle.

Admin & Config

- Added /mailbox admin convert <YAML|SQLITE|MYSQL> to <YAML|SQLITE|MYSQL>. - Added /mba convert <YAML|SQLITE|MYSQL> to <YAML|SQLITE|MYSQL>. - Added /mailbox admin import player <name1>[,<name2>]. - Added /mba import player <name1>[,<name2>]. - Added mailboxgui.admin.convert permission. - Added mailboxgui.admin.import permission. - Added money.admin-server-name config option for admin/server money mail. - Moved sounds.yml to the main MailboxGUI folder. - Added legacy mailboxsounds/sounds.yml migration.

Languages

- Updated language files to file-version: 5. - Added and updated language keys for the new 4.0.0 systems. - Updated non-English language files with translated section comments. - Kept language files organized to match the English file structure.

Compatibility

- Supports Spigot/Paper 1.18.2 through 1.21.11. - Supports 26.1.x, 26.1.1, and 26.1.2. - MailboxGUI is compiled with Java 17 for broad compatibility. - Use the Java version required by your server jar.

Dynmap Note

Dynmap marker support is not currently supported on 26.1.x / 26.1.1 / 26.1.2 until Dynmap has compatible builds. MailboxGUI will still run normally without Dynmap on those versions.

Important Upgrade Note

If upgrading from 3.1.2 or older, back up your plugins/MailboxGUI folder before updating. Legacy YAML data will be detected and migrated automatically. Existing legacy installs will stay on YAML storage until you manually convert to SQLite or MySQL.

MailboxGUI v3.1.2

Small maintenance update focused on anonymous bStats metrics and improved YAML synchronization.

Added

- Added bStats support for anonymous plugin metrics. - bStats helps track plugin usage, version adoption, and server environment information so future MailboxGUI development can be better prioritized. - Metrics can be disabled through the plugin config or globally through bStats.

Improved

- Improved YAML synchronization for config updates. - When the bundled config is updated, MailboxGUI now synchronizes the config structure while preserving existing configured values. - New config keys can be added automatically without forcing server owners to redo their current settings.

Upgrade Notes

- No mailbox data reset is required. - Existing mailbox, mail, package, COD, money mail, Post Office, and NPC data remain compatible. - Existing config values are preserved during config synchronization.

MailboxGUI v3.1.1

This is a small maintenance update focused on the Citizens NPC selector flow, bundled language cleanup, and config comment cleanup.

Added

- Added left-click cancellation while in NPC selection mode. - Left-click cancel now works for both: - Set Post Office NPC - Remove Post Office NPC - Added a new language key: - admin-npc-selector-cancelled

Changed

- NPC selector prompts now explain that admins can right-click an NPC to select it or left-click anywhere to cancel. - Admin NPC Tools GUI lore now includes the left-click cancel instruction. - Bundled language files were updated to file-version: 3. - Cleaned and corrected NPC setup/removal wording across bundled language files. - Removed the plugin version line from the top comment area of config.yml.

Fixed

- Fixed admins/players being stuck in NPC selection mode if they could not successfully update or remove an NPC. - Fixed NPC selection mode not having a left-click cancel path. - Fixed missing or incorrect NPC selector language text in several bundled language files.

Upgrade Notes

- No mailbox data reset is required. - No config reset is required. - config-version was not changed because the config structure did not change. - Existing language files using file-version: 2 will upgrade to file-version: 3. - The language upgrader updates old default NPC selector text while preserving customized server language edits.

Compatibility

- Minecraft/server compatibility remains unchanged from the previous 3.1.x release. - Citizens is required for Post Office NPC features. - Vault is only required for economy mail features. - Dynmap remains optional for map marker support.

MailboxGUI 3.1.0 — Compatibility Update

MailboxGUI 3.1.0 is a major compatibility-focused update that expands MailboxGUI into a broader one-jar build for modern Spigot/Paper servers.

Highlights

- Added one-jar support for Spigot/Paper 1.18.2 through 1.21.11 - Added support for Spigot/Paper 26.1.x - Removed the old -1.21 version suffix - Compiled with Java 17 for broader compatibility - Changed Spigot API baseline to 1.18.2 - Updated plugin API baseline to 1.18 - Improved sign compatibility across supported versions - Improved sound resolving across supported versions - Hardened Citizens NPC support for older and newer Citizens builds - Isolated Dynmap support so missing or incompatible Dynmap builds do not break startup - Improved Vault/economy hook detection and startup logging - Added safer multi-world location handling for missing or unloaded worlds - Fixed package receive/back-out behavior for partially withdrawn packages - Improved package handling for newer versions such as 1.20.6 - Added a safe language upgrade path from 3.0.0-1.21 → 3.1.0 - Added and reorganized supported language files

Tested Versions

1.18.2
1.19.4
1.20.1
1.20.6
1.21.10
26.1.x

Dynmap Note for 26.1.x

MailboxGUI works on 26.1.x, but Dynmap does not currently have a release build for that version. Dynmap marker support is therefore unsupported on 26.1.x for now. MailboxGUI will still run normally without Dynmap.

Language Updates

- Reorganized language files so all supported languages mirror the same key order - Added/updated translated language files - Added support for Dutch - Added support for Italian - Added support for Japanese - Added support for Korean - Added support for Polish - Added support for Russian - Added support for Ukrainian - Added support for Chinese Traditional - Improved language upgrader to preserve customized messages during upgrades

Upgrade Notes

Existing data should continue working when upgrading from 3.0.0-1.21 to 3.1.0: - Existing mailbox data remains compatible - Existing letters remain compatible - Existing packages remain compatible - Existing COD packages remain compatible - Existing money mail remains compatible - Existing Post Office boxes remain compatible - Existing Citizens Post Office NPCs remain compatible - Dynmap markers refresh from MailboxGUI data - Language files upgrade safely while preserving customized text As always, back up your server before updating.

MailboxGUI v3.0.0-1.21

This is a major feature update for MailboxGUI focused on Post Office systems, package experience, Dynmap support, admin tools, safer upgrades, and improved mail notifications.

New Features

- Added Post Office Boxes as public mailbox access points. - Added Post Office Registration admin GUI. - Added Registered Post Office Boxes list GUI. - Added Post Office Box set/remove selector flow. - Added Post Office Box sign numbering and automatic renumbering. - Added Package Experience support for player packages. - Added Package Experience support for admin/server packages. - Added Dynmap markers for: - Player mailboxes - Post Office boxes - Post Office NPCs - Added offline/login mail summaries with raw counts by mail type. - Added online delivery alerts with mail type details. - Added automatic inbox organization so mail no longer leaves empty gaps after claiming, deleting, or removing mail. - Added one-time pre-3.0 upgrade backup system. - Added safe language file upgrade system for upgrading from v2.1.

Improvements

- Improved Admin Tools GUI flow. - Moved NPC tools under Post Office Registration. - Improved player package compose GUI. - Improved admin package compose GUI. - Improved COD package handling. - Improved accepted COD package display. - Improved package lore to show included experience when applicable. - Improved Loaded/Unloaded mailbox status checks to verify physical mailbox blocks. - Improved WorldGuard/protected-region behavior for Post Office box opening. - Improved console startup and shutdown logging. - Updated config.yml layout and comments. - Updated sounds.yml with new sound options. - Reorganized all language files by category. - Added localized comments to language files.

Package Experience

Players can now add experience directly into packages. - Experience appears as a Bottle o’ Enchanting inside the package. - Experience uses a real package slot. - Re-adding experience updates the existing XP bottle. - Right-clicking the XP bottle in compose removes it. - Receivers can right-click or shift-left-click the XP bottle to deposit XP. Admin packages can also include experience without using the admin’s personal XP.

Post Office System

Post Office Boxes are public mailbox access points that can be opened by players. - Useful for spawn mailrooms, towns, hubs, and servers without Citizens. - Uses a normal single chest with a sign attached to the front. - No fence-post base required. - Admins can register, remove, and view PO Boxes through the GUI.

Dynmap Support

Dynmap support is optional. When Dynmap is installed, MailboxGUI can show markers for: - Player mailboxes - Post Office boxes - Post Office NPCs Default marker layer: ```text Mailboxes/PO Boxes/NPC

- Full Citizens 1.20 Compatibiltiy release

- Updated Admin Tools Inboxcheck Click behavior - Updated Citizens detection and fallback method - Updated config. Removed text length option from letters since 256 is the max chat length.