[--from <sender>] [--delay <seconds>] ``` --- ### Packages - Send item packages through clean GUIs. - Configurable package size. - Preserves Bukkit item metadata. - Supports custom names, lore, enchantments, potions, player heads, and custom plugin items. - Blocks nested package abuse. - Optional loaded shulker protection. - Updated package display colors for standard, COD, returned COD, accepted COD, and COD item-currency payment mail. - Works without Vault or an economy plugin. --- ### Package Experience - Add raw XP directly into packages. - XP appears as a Bottle o’ Enchanting. - XP uses a real package slot. - Re-adding XP updates the same bottle instead of adding duplicates. - Right-clicking the XP bottle in compose removes it. - Admin/API packages can include XP without using admin personal XP. --- ### Economy Features Economy features are optional and require Vault plus a compatible economy plugin. When available, MailboxGUI supports: - Player money mail. - Admin/server money mail. - Cash-On-Delivery packages. - COD preview before payment. - Accepted and returned COD package states. - Vault money COD prices. - Item-currency COD prices. - XP currency COD prices. - Saved item/template COD prices. - Combined COD prices. - Optional COD return recipient support for API and `/mba scod`. - Custom money display formatting to match the server economy style. - Vault2.0 custom currency names in money mail and Vault-money COD amount input. MailboxGUI 5.1.1 can safely parse plain numbers and formatted currency input such as: ```text 12 12 Coins 12 Dollars 12 <custom currency name> $12 12.50 1,000 ``` Example COD price formats: ```text 100 diamond:4,gold_nugget:2,xp:100 100,diamond:3 t:rare_sword:1,xp:250 ``` When Vault/economy support is unavailable, MailboxGUI automatically hides economy-only GUI options and continues functioning as a non-economy mailbox and package system. --- ### Offline & Online Notifications MailboxGUI supports offline mail delivery alerts and online delivery notifications. Offline summary modes: - **SIMPLE** — one summary message with total mail count. - **ADVANCED** — separate counts by mail type. - **OFF** — no offline login summary. Players can also control online mail sound alerts: ```text /mailbox settings notification soundalert <on|off> ``` MailboxGUI can show a floating new-mail paper icon above registered player mailboxes, including barrel mailboxes. --- ## Network Mode MailboxGUI 5.x includes optional network mode for multi-backend server setups. Network mode is useful for: - Velocity-style networks - Live + Legacy backend setups - multiple backend servers that should share the same mail data - servers that want network-wide recipient lookup and shared mail delivery MailboxGUI is installed on the backend servers that use mail. It does **not** need to be installed on the Velocity proxy itself. Network mode requires: ```text MySQL/MariaDB shared storage Redis Unique server-id per backend Same MailboxGUI version on each backend ``` Redis is used for cross-server refreshes, player presence, inbox state updates, paper notification updates, admin tool sync, reload requests, network notification payloads, and distributed safety locks. Single-server servers should leave network mode disabled. For full setup instructions, use the wiki: https://plugins.imagine-craft.net/mailboxgui/wiki/ --- ### Network Admin Tools In network mode, admin tools can show: - Server - World - Status Status examples: - **Loaded** — mailbox is physically loaded on the current backend. - **Unloaded** — mailbox belongs to the current backend but cannot currently be checked. - **Remote Server** — mailbox belongs to another backend. Admin removals, inbox edits, mail checks, signs, paper notifications, delayed mail, Book Letter flows, and COD item-currency flows sync safely across backend servers. --- ### Network Recipient Lookup Typed recipient lookup is network-aware. In network mode, MailboxGUI can use: - shared MailboxGUI player data - the shared network player index - optional local playerdata fallback Use: ```text /mba networkindex ``` on backends that have older local playerdata. This helps typed recipient lookup find legacy players who have not logged in since MailboxGUI network mode was installed. --- ## MailboxGUI-DiscBridge Addon MailboxGUI-DiscBridge is the official DiscordSRV notification addon for MailboxGUI. DiscBridge is available on SpigotMC and Modrinth for servers that want DiscordSRV-powered MailboxGUI mail notifications. It can send Discord notifications when MailboxGUI mail is delivered. > **MailboxGUI 5.1.x Compatibility:** For MailboxGUI 5.1.x, use **MailboxGUI-DiscBridge 1.1.0 or newer**. DiscBridge 1.1.0 adds support for Book Letter notifications, COD item-currency payment notifications, MailboxGUI 5.1.x `codPriceText` support, localized Discord message files, and player-selectable Discord DM languages. Use **MailboxGUI-DiscBridge 1.1.1 or newer** for the updated `zh_cn` and new `zh_hk` language files. Features include: - Discord DMs for eligible individual mail. - Channel notices for admin/API mass mail. - Support for Classic Letters, Book Letters, packages, COD packages, COD item-currency payment mail, returned COD packages, and money mail. - Player opt-in/out commands. - Ignore sender and ignore admin-mail options. - LOCAL mode for standalone servers. - NETWORK_NODE mode for MailboxGUI network setups. - Duplicate event protection. - Optional queued mass-mail DMs. - Localized Discord message templates. For standalone servers, run MailboxGUI, DiscordSRV, and DiscBridge together on the same backend. For Velocity-style networks, install MailboxGUI on every mail backend, but install DiscordSRV and DiscBridge on only one backend. Set DiscBridge to: ```text mode: NETWORK_NODE ``` DiscBridge does not run on Velocity itself. ### DiscBridge Downloads | Platform | MailboxGUI-DiscBridge Page | |---|---| | SpigotMC | [MailboxGUI-DiscBridge on SpigotMC](https://www.spigotmc.org/resources/mailboxgui-discbridge-discordsrv-mail-notifications-for-mailboxgui.135557/) | | Modrinth | [MailboxGUI-DiscBridge on Modrinth](https://modrinth.com/plugin/mailboxgui-discbridge) | --- ## Storage System MailboxGUI supports: ```text YAML SQLite MySQL ``` Fresh installs default to SQLite. Legacy YAML installs are detected automatically and kept on YAML unless the admin manually converts storage later. This protects old servers upgrading from previous MailboxGUI versions. Storage conversion is handled through: ```text /mailbox admin convert <YAML|SQLITE|MYSQL> /mba convert <YAML|SQLITE|MYSQL> ``` Admins can also check the current storage mode with: ```text /mailbox admin convert current /mba convert current ``` In network mode, storage conversion is disabled to protect shared mail data. Convert to MySQL before enabling network mode. --- ### Admin Tools MailboxGUI includes a full admin tools system for managing mailboxes, post offices, inboxes, and server mail. Admins can: - Send admin/server Classic Letters. - Send admin/server Book Letters. - Send admin/server packages. - Send admin/server money mail. - Send packages with XP. - Send COD packages. - Send COD item-currency packages. - Send to all players, online players, offline players, or selected recipients. - Inspect player inboxes. - Read and delete Book Letters safely from admin inbox check. - Manage package mail from admin inbox check. - Remove individual mail. - Empty inboxes when needed. - Register/unregister player mailboxes. - Register/remove Post Office boxes. - View network-aware mailbox and PO box ownership. - Set/remove Citizens Post Office NPCs. - Save and send item templates. - Clean generated backup files after confirming upgraded data is working. - Manually check for plugin updates. Open the admin tools menu with: ```text /mailbox admin tools ``` Admin Book Letter command: ```text /mba sla <recipient[,recipient2]|allplayers|onlineplayers> '<message>' --title <title> [--from <sender>] [--delay <seconds>] ``` Update commands: ```text /mailbox admin updatecheck /mba updatecheck /mba update /mba update confirm ``` The update command downloads and stages the new MailboxGUI jar for the next restart. On Velocity-style networks, run the update command on each backend server that has MailboxGUI installed. --- ### API & Plugin Integration MailboxGUI includes a public API for other plugins to send mail through MailboxGUI. The API can send: - Classic Letters - Book Letters - Regular packages - Cash-On-Delivery packages - COD item-currency packages - Money mail - Multiple-recipient mail - Custom sender display names - Delayed mail - Full Bukkit `ItemStack` package contents - Package XP - Optional COD payment/return recipient behavior MailboxGUI 5.1.x includes delivery event metadata and network event support used by addon plugins such as MailboxGUI-DiscBridge. Maven dependency: ```xml <dependency> <groupId>io.github.rismr1</groupId> <artifactId>mailboxgui-api</artifactId> <version>5.1.1</version> <scope>provided</scope> </dependency> ``` Full API usage and developer documentation are available on the wiki. --- ### PlaceholderAPI PlaceholderAPI is optional. When installed, MailboxGUI registers `%mailboxgui_*%` placeholders for mailbox status, inbox counts, pending mail counts, storage type, delayed mail queue count, package slot limit, and more. MailboxGUI still works normally without PlaceholderAPI. --- ## Commands & Permissions MailboxGUI includes player commands, admin commands, admin/console sending commands, item template commands, and detailed permission nodes. Optional command mailbox access: ```text /mailbox open /mb open ``` This feature is disabled by default and can be enabled with: ```yml mailbox: command-open: enabled: true ``` Required permissions: ```text mailboxgui.player.use mailboxgui.player.open ``` For full commands, permissions, usage examples, screenshots, setup walkthroughs, and configuration details, please visit: https://plugins.imagine-craft.net/mailboxgui/wiki/ This keeps the project page easier to read while the wiki provides the complete reference. --- ## Language Support MailboxGUI includes bundled language files for: English, Español, Nederlands, Italiano, Français, Deutsch, Svenska, Polski, 日本語, 한국어, Русский, Українська, 中文（简体）, 中文（香港繁體）, 中文（繁體） Language files are stored in: ```text plugins/MailboxGUI/language/ ``` MailboxGUI can automatically use a player's Minecraft client locale when supported. MailboxGUI 5.1.1 updates active language files to `file-version: 14` and adds `messages_zh_hk.yml`. Chinese language files now include: ```text messages_zh_cn.yml messages_zh_hk.yml messages_zh_tw.yml ``` Special thanks to project supporter and contributor **nice** for providing the updated **Simplified Chinese (`zh_cn`)** language file and the new **Hong Kong Traditional Chinese (`zh_hk`)** language file. --- ## Upgrade Safety MailboxGUI includes safe upgrade handling for older installs. When upgrading from older versions: - Legacy YAML data is detected automatically. - Existing legacy YAML installs stay on YAML storage unless manually converted. - Old data is copied into the current data structure. - Old mail items are upgraded safely. - Package, COD, XP, and item-currency package inbox items are refreshed for current preview and admin management lore. - Old language files are upgraded with missing keys and current structure. - Existing customized language values are preserved where possible. - Backup files are generated before important upgrade operations. - `/mba clean` can clean newer MailboxGUI-generated backup folders after confirming the upgrade is working. You should not need to wipe old mail data when upgrading from supported older versions. For network setups, follow the wiki setup order before enabling network mode. ## Download Goals MailboxGUI is currently growing on Modrinth, and every download helps the project reach more server owners. Current Modrinth downloads: **202** Milestones: - [X] **150 downloads** — Growing community milestone - [X] **200 downloads** — Major discovery milestone - **250 downloads** — Big support milestone - **300 downloads** — Expanding server reach milestone If MailboxGUI has been useful for your server, downloading, following, and giving the project a heart on Modrinth helps support continued development and helps other server owners discover the plugin. --- ## Contributors Special thanks to project supporter and contributor **nice** for the updated **Simplified Chinese (`zh_cn`)** and new **Hong Kong Traditional Chinese (`zh_hk`)** language files for MailboxGUI 5.1.1. **Author:** Rismr1 </article></body></html>

![MailboxGUI Banner](https://github.com/Rismr1/MailboxGUI/blob/main/assets/MailboxGUIBannerlogo.png?raw=true) # MailboxGUI ### Advanced Mailbox, Package, Letter, Economy & Network Mail System **Spigot / Paper / Purpur 1.18.2 - 1.21.11 + 26.1.x / 26.2.x** MailboxGUI is a complete GUI-based mail system for Minecraft servers. Players and admins can send **Classic Letters**, **Book Letters**, **packages**, **Cash-On-Delivery packages**, **item-currency COD packages**, **package experience**, and **money mail** through physical mailboxes, public Post Office boxes, Citizens NPCs, commands, and a public API. MailboxGUI can be used as a full economy-connected mail system with Vault, or as a simple immersive mailbox system without economy features. If Vault or an economy plugin is not installed, MailboxGUI automatically adapts by hiding money and COD options while keeping letters, Book Letters, packages, public mail access, and mailbox gameplay available. MailboxGUI 5.1.1 continues the 5.x network-ready release line with Vault2.0 custom currency support, improved money/COD chat-input parsing, updated Chinese language support, the new `zh_hk` language file, and all 5.1.0 Book Letter, COD item-currency, API, admin inbox, network, and Paper/Purpur 26.2.x compatibility features. --- ## MailboxGUI Plugin Showcase / Tutorial Video Watch MailboxGUI in action, including physical player mailboxes, public Post Office boxes, Citizens NPC access, Classic Letters, Book Letters, item packages, package experience, Cash-On-Delivery packages, item-currency COD packages, money mail, admin tools, and more. --- ## MailboxGUI vs MailBox Feature Comparison This table is a feature-scope comparison between **MailboxGUI by Rismr1** and **MailBox by ikafly144**. It is meant to help server owners quickly understand which plugin best fits their setup. | Feature / Area | MailboxGUI by Rismr1 | MailBox by ikafly144 | |---|---|---| | Main focus | ✅ Yes — full physical mailbox, package, letter, economy, admin, API, Discord-addon, and network-ready mail system | ✅ Yes — Paper GUI mail plugin with inbox/send menus, templates, and attachments | | Server compatibility target | ✅ Yes — Spigot/Paper/Purpur 1.18.2 through 1.21.11, plus 26.1.x and 26.2.x | ✅ Yes — Paper 1.21.6+ target | | Folia support | ❌ No — standard Spigot/Paper/Purpur target; Folia is not listed as supported | ✅ Yes — declares Folia support | | Physical player mailboxes | ✅ Yes — chest/barrel/sign mailbox access | ❌ No — focuses on GUI mail access | | Public Post Office boxes | ✅ Yes — shared public access points for each player’s own inbox | ❌ No — public Post Office boxes are not part of the feature set | | Citizens Post Office NPCs | ✅ Yes — optional Citizens NPC mail access | ❌ No — Citizens Post Office NPCs are not part of the feature set | | GUI inbox and send menus | ✅ Yes — player and admin GUI mail workflows | ✅ Yes — GUI inbox and sending workflows | | Classic text letters/messages | ✅ Yes — Classic Letters, admin/server letters, timestamps, and reply flow | ✅ Yes — message-based mail with subject/content support | | Book and Quill mail | ✅ Yes — Book Letters added in 5.1.0 | ❌ No — Book and Quill mail is not part of the feature set | | Item packages / item attachments | ✅ Yes — item packages preserve Bukkit item metadata | ✅ Yes — item attachments are supported | | Command attachments | ❌ No — claimable command attachments are not part of the feature set | ✅ Yes — mail attachments can run commands when claimed | | Message attachments | ✅ Yes — Classic Letters and Book Letters cover player/admin message delivery | ✅ Yes — message attachments are supported | | Per-attachment expiration | ❌ No — delayed mail and draft/session safety are supported, but individual attachment expiration is not part of the feature set | ✅ Yes — attachments can have expiration durations | | Custom attachment display icon/name | ❌ No — package display is type/item based, not a general per-attachment custom icon/name system | ✅ Yes — attachments can define display names and preview icons | | Package XP | ✅ Yes — XP can be added directly into packages | ❌ No — package XP is not part of the feature set | | Vault economy support | ✅ Yes — money mail and Vault-money COD prices | ✅ Yes — Vault economy value support | | COD package flow | ✅ Yes — preview, accept/decline, returned state, and return-recipient behavior | ❌ No — full COD package accept/decline/return workflow is not part of the feature set | | Item-currency COD pricing | ✅ Yes — supports item currency, XP currency, saved templates, and combined prices | ❌ No — item-currency COD pricing is not part of the feature set | | Admin mass mail | ✅ Yes — all players, online players, offline players, and selected recipients | ✅ Yes — template/send command workflow | | Mail templates | ✅ Yes — item templates for package/admin rewards | ✅ Yes — mail templates and template editing | | Recurring/auto-send templates | ❌ No — one-time delayed mail is supported, but recurring auto-send templates are not part of the feature set | ✅ Yes — templates can support auto-send timing with start, end, interval, and permission settings | | Storage | ✅ Yes — YAML legacy support, SQLite default, MySQL support, and safe conversion tools | ✅ Yes — H2 and MySQL storage | | H2 local database | ❌ No — SQLite is the local default database | ✅ Yes — H2 local storage is supported | | Network mode | ✅ Yes — MySQL + Redis network mode for multi-backend / Velocity-style setups | ❌ No — Redis-backed multi-backend network mode is not part of the feature set | | Discord notifications | ✅ Yes — optional MailboxGUI-DiscBridge addon with LOCAL and NETWORK_NODE modes | ❌ No — Discord notification addon support is not part of the feature set | | Public API | ✅ Yes — MailboxGUI API 5.1.0 | ✅ Yes — public API support | | PlaceholderAPI support | ✅ Yes — optional MailboxGUI placeholders | ✅ Yes — PlaceholderAPI support | | Built-in update commands | ✅ Yes — website-powered update check/staging commands | ❌ No — built-in staged update commands are not part of the feature set | | Language files | ✅ Yes — 15 bundled languages with upgrade-aware synchronization, including `zh_cn`, `zh_hk`, and `zh_tw` | ❌ No — full bundled multi-language file set is not part of the feature set | | Best fit | ✅ Yes — best for servers wanting physical mailboxes, Book Letters, packages, COD, economy mail, Post Offices, NPCs, Discord notifications, API integrations, and network mode | ✅ Yes — best for servers wanting a lighter Paper/Folia mail GUI with templates, attachments, command attachments, and auto-send template options | > This comparison is not meant to put down another project. MailBox has useful strengths such as Folia support, command attachments, per-attachment expiration, custom attachment icons/names, H2 storage, and recurring/auto-send templates. MailboxGUI is built for servers that want a larger physical mailbox, package, COD, admin, API, Discord-addon, and network-ready mail system. ## MailboxGUI 5.1.1 Highlights MailboxGUI 5.1.1 is the **Vault2.0 Custom Currency and Language Update**. - Added improved **Vault2.0 custom currency support** for money mail and Vault-money COD amount input. - Improved amount parsing for custom currency names, currency symbols, comma-formatted numbers, color codes, and hidden formatting. - Fixed compatibility issues where renamed Vault2.0 currencies could cause COD or money input prompts to reject valid values. - Improved chat-input cleanup for `cancel`, `off`, XP amounts, COD amounts, money amounts, typed recipient input, Book Letter drafts, admin prompts, and Post Office name prompts. - Updated the **Simplified Chinese (`zh_cn`)** language file. - Added new **Hong Kong Traditional Chinese (`zh_hk`)** language support. - Updated active language files to `file-version: 14`. - Added language upgrade support so old default `zh_cn` values can upgrade to the new bundled translation while preserving server-owner custom edits. - Updated `/mba clean` so newer MailboxGUI-generated backup folders can be cleaned after the admin confirms the plugin is working correctly. - MailboxGUI 5.1.0 compatibility features are still included: Book Letters, item-currency COD, API payloads, admin inbox tools, network validation, and Paper/Purpur 26.2.x support. ### Previous 5.1.0 Book Letter and COD Highlights MailboxGUI 5.1.0 was the **Book Letters, COD Item Currency, API & 26.2 Support Update**. - Added **Book Letters** alongside Classic Paper Letters. - Added real Book and Quill writing flow with protected draft handling. - Added sign-and-close Book Letter sending. - Added safe Book Letter cancel/logout cleanup and original hotbar item restoration. - Added player-sent Book Letter reply links while reading from the inbox. - Admin/server/API Book Letters do not include reply links. - Added `/mba sla` for admin/server Book Letter sending. - Added expanded **COD item-currency** support. - COD prices can now use Vault money, item currency, XP currency, saved item templates, or combined prices. - Added **COD item-currency payment mail**. - Updated package display colors, including Purple Shulker Box for COD item-currency payment mail. - Improved `/mba tools inbox check` Book Letter and package management behavior. - Updated MailboxGUI API to **5.1.0** for the Book Letter and COD item-currency payload additions. - Added Book Letter and COD item-currency delivery payload support for addon plugins. - Updated config to `config-version: 12`. - Updated mail data to `data-version: 5`. - **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.** ### Vault2.0 Custom Currency Support MailboxGUI 5.1.1 improves compatibility with Vault2.0 custom currency names. If a server renames its Vault2.0 currency, MailboxGUI now cleans and normalizes the chat amount input before parsing it. This helps money mail and Vault-money COD prompts accept values like: ```text 12 12 Coins 12 Dollars 12 $12 12.50 1,000 ``` This update also improves `cancel` and `off` handling in chat-input prompts, including money mail, COD, XP, typed recipient, Book Letter draft, admin prompt, and Post Office name input flows. ### Previous 5.0.x Network Support Highlights MailboxGUI 5.0.x added optional multi-backend network support with MySQL/MariaDB and Redis, network-aware admin tools, safer shared mail handling, player mailbox management, update commands, and MailboxGUI-DiscBridge support. - Added optional **network mode** for multi-backend / Velocity-style setups. - Added shared **MySQL/MariaDB** support for network mail data. - Added **Redis-backed network synchronization** for mail delivery, inbox refreshes, paper notifications, admin tools, reloads, and safety locks. - Added network-aware typed recipient lookup for player and admin mail. - Added `/mba networkindex` to index backend playerdata into shared network lookup. - Added network-aware admin tools for registered player mailboxes and Post Office boxes. - Added server/world/status display for mailbox management while network mode is enabled. - Added **Remote Server** status for mailboxes and PO boxes registered on another backend. - Added network-safe inbox, paper notification, sign, admin inbox, mailbox removal, and Post Office refresh behavior. - Added `/mailbox unregister` GUI with **Selection Mode** and **Manage Personal Mailboxes**. - Added optional `/mailbox open` and `/mb open` command access. - Added `offlineplayers` admin recipient targeting. - Added website-powered update checks and staged update commands. - Added network-mode warnings for update commands because each backend must be updated separately. --- ## Support & Documentation **GitHub:** https://github.com/Rismr1/MailboxGUI **Discord Support:** https://discord.gg/kggbGwRt42 **Issues / Feature Requests:** https://github.com/Rismr1/MailboxGUI/issues For detailed setup, commands, permissions, configuration, storage conversion, Book Letter usage, COD item-currency usage, API usage, screenshots, troubleshooting, and network setup examples, please use the official wiki: https://plugins.imagine-craft.net/mailboxgui/wiki/ > **Network Setup Note:** If you are using MailboxGUI on a Velocity-style network or multiple backend servers, use the wiki’s Network Configuration section. Network mode requires MySQL/MariaDB shared storage and Redis. Storage should be converted to MySQL before enabling network mode. --- ## Active Plugin & Quick Support MailboxGUI is actively maintained. If you need help, find a bug, or want to request a feature, join the Discord support server or open a GitHub ticket. If MailboxGUI has been useful for your server and you love the plugin, please consider giving it a heart on Modrinth. It helps other server owners discover the project and supports continued development. --- ## Designed For - RPG servers - Economy servers - Survival servers - Town and city servers - Quest and roleplay communities - Multi-world server setups - Spawn hubs and public service areas - Velocity-style server networks - Legacy world / secondary backend setups - Servers that want immersive physical mailboxes - Servers that want Book and Quill style in-game mail - Servers that want API, command, or menu-driven mail integration with other plugins - Servers that want a mail system that still works cleanly without economy support --- ## Compatibility ### Supported Server Versions ```text Spigot/Paper/Purpur 1.18.2 through 1.21.11 Spigot/Paper/Purpur 26.1.x Spigot/Paper/Purpur 26.2.x ``` > **Important 26.2 Note:** MailboxGUI **5.1.0 or newer is required for Paper/Purpur 26.2.x compatibility**. Older versions, including MailboxGUI 5.0.1, do not support 26.2.x sign updating correctly. Use **MailboxGUI 5.1.1 or newer** if you also need Vault2.0 custom currency support. ### Java Notes - MailboxGUI is compiled with Java 17 for broad compatibility. - Use the Java version required by your server jar. - Java 21 is recommended for modern 1.20.6+ and 1.21.x servers. - 26.1.x and 26.2.x should use the Java version required by that server build. ### Optional Dependencies - **Vault** — required for money mail and Vault-money COD package payments. - **Vault2.0** — supported for custom currency names in money mail and Vault-money COD amount input. - **Economy plugin** — required for actual economy transactions. - **Citizens** — optional for Post Office NPCs. - **Dynmap** — optional for map markers where supported. - **PlaceholderAPI** — optional for `%mailboxgui_*%` placeholders. - **MySQL/MariaDB** — required only for network mode. - **Redis** — required only for network mode. > **Important Dynmap Note:** Dynmap marker support is currently **not supported on 26.1.x or 26.2.x**. MailboxGUI itself still works without Dynmap, and all core mailbox, inbox, Book Letter, package, COD, money mail, storage, API, and network features remain available. > **Important:** Multiverse-Core is not required. MailboxGUI uses Bukkit world/location handling and includes safe checks for missing or unloaded worlds. --- ## Core Features ### Physical Player Mailboxes Players can register physical mailbox locations in the world. A standard player mailbox uses: ```text Fence Post Normal Single Chest OR Barrel placed on top Sign attached to the front face of the chest/barrel ``` The sign must be attached to the front face of the chest or barrel. Players can register by clicking the sign or container during registration mode. MailboxGUI supports multiple mailboxes per player with configurable limits. Default signs use clear MailboxGUI branding and **Personal Mail** wording. Players can use `/mailbox unregister` to open an unregister menu with: - **Selection Mode** — right-click a physical mailbox chest/barrel/sign to unregister it. - **Manage Personal Mailboxes** — unregister personal mailboxes from a GUI without walking to the mailbox. > MailboxGUI primarily uses physical access points. Players normally access mail through a registered mailbox, a public Post Office box, or a Post Office NPC. Servers can also enable optional command-based access with `/mailbox open` or `/mb open` for backend servers or network setups where physical access points are not available. --- ### Public Post Office Boxes Post Office boxes are public mailbox access points for spawn areas, towns, cities, hubs, and shared mailrooms. A Post Office box uses: ```text Normal Single Chest OR Barrel Sign attached to the front face of the chest/barrel ``` Post Office boxes do not require a fence-post base. They are not registered to one specific player and they are not shared inventories. They are shared access points that allow any permitted player to access their own personal mail menu. Default signs use clear **Public Access** wording. In network mode, admin tools can show which backend server and world a Post Office box belongs to. --- ### Citizens Post Office NPCs MailboxGUI supports optional Citizens Post Office NPCs. Admins can mark Citizens NPCs as Post Office NPCs, allowing players to right-click them to open MailboxGUI access. Citizens is optional. If Citizens is not installed, MailboxGUI continues working normally. --- ### Classic Letters - Send player-written Classic Letters. - Supports offline delivery. - Supports player reply flow. - Supports admin/server letters. - Includes polished letter lore and timestamps. - Works without Vault or an economy plugin. --- ### Book Letters MailboxGUI 5.1.0 adds Book Letters alongside Classic Paper Letters. Players can send Book Letters through: ```text /mailbox Send Mail Letter Book Letter Select Recipient ``` Admins can send Book Letters through: ```text /mailbox admin tools Send Mail Letter Book Letter ``` Book Letter features: - Real Book and Quill writing flow. - Protected temporary Book and Quill draft. - 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 are removed when a Book Letter is taken from the inbox. Admin/server Book Letter command: ```text /mba sla '' --title [--from <sender>] [--delay <seconds>] ``` --- ### Packages - Send item packages through clean GUIs. - Configurable package size. - Preserves Bukkit item metadata. - Supports custom names, lore, enchantments, potions, player heads, and custom plugin items. - Blocks nested package abuse. - Optional loaded shulker protection. - Updated package display colors for standard, COD, returned COD, accepted COD, and COD item-currency payment mail. - Works without Vault or an economy plugin. --- ### Package Experience - Add raw XP directly into packages. - XP appears as a Bottle o’ Enchanting. - XP uses a real package slot. - Re-adding XP updates the same bottle instead of adding duplicates. - Right-clicking the XP bottle in compose removes it. - Admin/API packages can include XP without using admin personal XP. --- ### Economy Features Economy features are optional and require Vault plus a compatible economy plugin. When available, MailboxGUI supports: - Player money mail. - Admin/server money mail. - Cash-On-Delivery packages. - COD preview before payment. - Accepted and returned COD package states. - Vault money COD prices. - Item-currency COD prices. - XP currency COD prices. - Saved item/template COD prices. - Combined COD prices. - Optional COD return recipient support for API and `/mba scod`. - Custom money display formatting to match the server economy style. - Vault2.0 custom currency names in money mail and Vault-money COD amount input. MailboxGUI 5.1.1 can safely parse plain numbers and formatted currency input such as: ```text 12 12 Coins 12 Dollars 12 <custom currency name> $12 12.50 1,000 ``` Example COD price formats: ```text 100 diamond:4,gold_nugget:2,xp:100 100,diamond:3 t:rare_sword:1,xp:250 ``` When Vault/economy support is unavailable, MailboxGUI automatically hides economy-only GUI options and continues functioning as a non-economy mailbox and package system. --- ### Offline & Online Notifications MailboxGUI supports offline mail delivery alerts and online delivery notifications. Offline summary modes: - **SIMPLE** — one summary message with total mail count. - **ADVANCED** — separate counts by mail type. - **OFF** — no offline login summary. Players can also control online mail sound alerts: ```text /mailbox settings notification soundalert <on|off> ``` MailboxGUI can show a floating new-mail paper icon above registered player mailboxes, including barrel mailboxes. --- ## Network Mode MailboxGUI 5.x includes optional network mode for multi-backend server setups. Network mode is useful for: - Velocity-style networks - Live + Legacy backend setups - multiple backend servers that should share the same mail data - servers that want network-wide recipient lookup and shared mail delivery MailboxGUI is installed on the backend servers that use mail. It does **not** need to be installed on the Velocity proxy itself. Network mode requires: ```text MySQL/MariaDB shared storage Redis Unique server-id per backend Same MailboxGUI version on each backend ``` Redis is used for cross-server refreshes, player presence, inbox state updates, paper notification updates, admin tool sync, reload requests, network notification payloads, and distributed safety locks. Single-server servers should leave network mode disabled. For full setup instructions, use the wiki: https://plugins.imagine-craft.net/mailboxgui/wiki/ --- ### Network Admin Tools In network mode, admin tools can show: - Server - World - Status Status examples: - **Loaded** — mailbox is physically loaded on the current backend. - **Unloaded** — mailbox belongs to the current backend but cannot currently be checked. - **Remote Server** — mailbox belongs to another backend. Admin removals, inbox edits, mail checks, signs, paper notifications, delayed mail, Book Letter flows, and COD item-currency flows sync safely across backend servers. --- ### Network Recipient Lookup Typed recipient lookup is network-aware. In network mode, MailboxGUI can use: - shared MailboxGUI player data - the shared network player index - optional local playerdata fallback Use: ```text /mba networkindex ``` on backends that have older local playerdata. This helps typed recipient lookup find legacy players who have not logged in since MailboxGUI network mode was installed. --- ## MailboxGUI-DiscBridge Addon MailboxGUI-DiscBridge is the official DiscordSRV notification addon for MailboxGUI. DiscBridge is available on SpigotMC and Modrinth for servers that want DiscordSRV-powered MailboxGUI mail notifications. It can send Discord notifications when MailboxGUI mail is delivered. > **MailboxGUI 5.1.x Compatibility:** For MailboxGUI 5.1.x, use **MailboxGUI-DiscBridge 1.1.0 or newer**. DiscBridge 1.1.0 adds support for Book Letter notifications, COD item-currency payment notifications, MailboxGUI 5.1.x `codPriceText` support, localized Discord message files, and player-selectable Discord DM languages. Use **MailboxGUI-DiscBridge 1.1.1 or newer** for the updated `zh_cn` and new `zh_hk` language files. Features include: - Discord DMs for eligible individual mail. - Channel notices for admin/API mass mail. - Support for Classic Letters, Book Letters, packages, COD packages, COD item-currency payment mail, returned COD packages, and money mail. - Player opt-in/out commands. - Ignore sender and ignore admin-mail options. - LOCAL mode for standalone servers. - NETWORK_NODE mode for MailboxGUI network setups. - Duplicate event protection. - Optional queued mass-mail DMs. - Localized Discord message templates. For standalone servers, run MailboxGUI, DiscordSRV, and DiscBridge together on the same backend. For Velocity-style networks, install MailboxGUI on every mail backend, but install DiscordSRV and DiscBridge on only one backend. Set DiscBridge to: ```text mode: NETWORK_NODE ``` DiscBridge does not run on Velocity itself. ### DiscBridge Downloads | Platform | MailboxGUI-DiscBridge Page | |---|---| | SpigotMC | [MailboxGUI-DiscBridge on SpigotMC](https://www.spigotmc.org/resources/mailboxgui-discbridge-discordsrv-mail-notifications-for-mailboxgui.135557/) | | Modrinth | [MailboxGUI-DiscBridge on Modrinth](https://modrinth.com/plugin/mailboxgui-discbridge) | --- ## Storage System MailboxGUI supports: ```text YAML SQLite MySQL ``` Fresh installs default to SQLite. Legacy YAML installs are detected automatically and kept on YAML unless the admin manually converts storage later. This protects old servers upgrading from previous MailboxGUI versions. Storage conversion is handled through: ```text /mailbox admin convert <YAML|SQLITE|MYSQL> /mba convert <YAML|SQLITE|MYSQL> ``` Admins can also check the current storage mode with: ```text /mailbox admin convert current /mba convert current ``` In network mode, storage conversion is disabled to protect shared mail data. Convert to MySQL before enabling network mode. --- ### Admin Tools MailboxGUI includes a full admin tools system for managing mailboxes, post offices, inboxes, and server mail. Admins can: - Send admin/server Classic Letters. - Send admin/server Book Letters. - Send admin/server packages. - Send admin/server money mail. - Send packages with XP. - Send COD packages. - Send COD item-currency packages. - Send to all players, online players, offline players, or selected recipients. - Inspect player inboxes. - Read and delete Book Letters safely from admin inbox check. - Manage package mail from admin inbox check. - Remove individual mail. - Empty inboxes when needed. - Register/unregister player mailboxes. - Register/remove Post Office boxes. - View network-aware mailbox and PO box ownership. - Set/remove Citizens Post Office NPCs. - Save and send item templates. - Clean generated backup files after confirming upgraded data is working. - Manually check for plugin updates. Open the admin tools menu with: ```text /mailbox admin tools ``` Admin Book Letter command: ```text /mba sla <recipient[,recipient2]|allplayers|onlineplayers> '<message>' --title <title> [--from <sender>] [--delay <seconds>] ``` Update commands: ```text /mailbox admin updatecheck /mba updatecheck /mba update /mba update confirm ``` The update command downloads and stages the new MailboxGUI jar for the next restart. On Velocity-style networks, run the update command on each backend server that has MailboxGUI installed. --- ### API & Plugin Integration MailboxGUI includes a public API for other plugins to send mail through MailboxGUI. The API can send: - Classic Letters - Book Letters - Regular packages - Cash-On-Delivery packages - COD item-currency packages - Money mail - Multiple-recipient mail - Custom sender display names - Delayed mail - Full Bukkit `ItemStack` package contents - Package XP - Optional COD payment/return recipient behavior MailboxGUI 5.1.x includes delivery event metadata and network event support used by addon plugins such as MailboxGUI-DiscBridge. Maven dependency: ```xml <dependency> <groupId>io.github.rismr1</groupId> <artifactId>mailboxgui-api</artifactId> <version>5.1.1</version> <scope>provided</scope> </dependency> ``` Full API usage and developer documentation are available on the wiki. --- ### PlaceholderAPI PlaceholderAPI is optional. When installed, MailboxGUI registers `%mailboxgui_*%` placeholders for mailbox status, inbox counts, pending mail counts, storage type, delayed mail queue count, package slot limit, and more. MailboxGUI still works normally without PlaceholderAPI. --- ## Commands & Permissions MailboxGUI includes player commands, admin commands, admin/console sending commands, item template commands, and detailed permission nodes. Optional command mailbox access: ```text /mailbox open /mb open ``` This feature is disabled by default and can be enabled with: ```yml mailbox: command-open: enabled: true ``` Required permissions: ```text mailboxgui.player.use mailboxgui.player.open ``` For full commands, permissions, usage examples, screenshots, setup walkthroughs, and configuration details, please visit: https://plugins.imagine-craft.net/mailboxgui/wiki/ This keeps the project page easier to read while the wiki provides the complete reference. --- ## Language Support MailboxGUI includes bundled language files for: English, Español, Nederlands, Italiano, Français, Deutsch, Svenska, Polski, 日本語, 한국어, Русский, Українська, 中文（简体）, 中文（香港繁體）, 中文（繁體） Language files are stored in: ```text plugins/MailboxGUI/language/ ``` MailboxGUI can automatically use a player's Minecraft client locale when supported. MailboxGUI 5.1.1 updates active language files to `file-version: 14` and adds `messages_zh_hk.yml`. Chinese language files now include: ```text messages_zh_cn.yml messages_zh_hk.yml messages_zh_tw.yml ``` Special thanks to project supporter and contributor **nice** for providing the updated **Simplified Chinese (`zh_cn`)** language file and the new **Hong Kong Traditional Chinese (`zh_hk`)** language file. --- ## Upgrade Safety MailboxGUI includes safe upgrade handling for older installs. When upgrading from older versions: - Legacy YAML data is detected automatically. - Existing legacy YAML installs stay on YAML storage unless manually converted. - Old data is copied into the current data structure. - Old mail items are upgraded safely. - Package, COD, XP, and item-currency package inbox items are refreshed for current preview and admin management lore. - Old language files are upgraded with missing keys and current structure. - Existing customized language values are preserved where possible. - Backup files are generated before important upgrade operations. - `/mba clean` can clean newer MailboxGUI-generated backup folders after confirming the upgrade is working. You should not need to wipe old mail data when upgrading from supported older versions. For network setups, follow the wiki setup order before enabling network mode. ## Download Goals MailboxGUI is currently growing on Modrinth, and every download helps the project reach more server owners. Current Modrinth downloads: **202** Milestones: - [X] **150 downloads** — Growing community milestone - [X] **200 downloads** — Major discovery milestone - **250 downloads** — Big support milestone - **300 downloads** — Expanding server reach milestone If MailboxGUI has been useful for your server, downloading, following, and giving the project a heart on Modrinth helps support continued development and helps other server owners discover the plugin. --- ## Contributors Special thanks to project supporter and contributor **nice** for the updated **Simplified Chinese (`zh_cn`)** and new **Hong Kong Traditional Chinese (`zh_hk`)** language files for MailboxGUI 5.1.1. **Author:** Rismr1 </article></body></html>

mysticdrew

Badges