![MailboxGUI Banner](https://github.com/Rismr1/MailboxGUI/blob/main/assets/MailboxGUIBannerlogo.png?raw=true) # MailboxGUI ### Advanced Mailbox, Package, Letter & Database System **Spigot / Paper 1.18.2 - 1.21.11 + 26.1.x / 26.1.1 / 26.1.2** MailboxGUI is a complete GUI-based mail system for Minecraft servers. Players and admins can send **letters**, **packages**, **Cash-On-Delivery packages**, **package experience**, and **money mail** through physical mailboxes, public Post Office boxes, Citizens NPCs, and a clean inventory GUI. **MailboxGUI 4.1.x** adds a public API, admin/console sending commands, item templates, PlaceholderAPI support, persistent delayed mail, and stronger plugin integration tools. Other plugins can integrate with MailboxGUI through the API or by running admin/console sending commands for more flexible mail delivery. --- ## 4.1.x Update Highlights - Added a public API for plugin integrations. - Added admin/console sending commands for letters, packages, COD packages, and money mail. - Added item templates for sending custom items, enchanted items, written books, lore items, and plugin-created items through commands. - Added PlaceholderAPI support with `%mailboxgui_*%` placeholders. - Added persistent delayed mail that survives server restarts. - Added delayed mail support for YAML, SQLite, MySQL, and `/mba convert`. - Added better typed-recipient handling with server playerdata auto-import. - Added COD return-recipient support with `/mba scod r:`. - Added 4.1.1 storage polish for item templates, MySQL validation, and `/mba convert` coverage. --- ## Support **GitHub:** https://github.com/Rismr1/MailboxGUI **Wiki:** https://plugins.imagine-craft.net/mailboxgui/wiki/ **Discord Support:** https://discord.gg/67RsHugqBp **Issues / Feature Requests:** https://github.com/Rismr1/MailboxGUI/issues --- ## Active Plugin & Quick Support MailboxGUI is actively maintained and support is quick. If you need help, find a bug, or want to request a feature, join the Discord support server or open a GitHub ticket. Support requests are actively watched and handled as soon as possible. --- ## Designed For - RPG Servers - Economy Servers - Survival Servers - Town / City Servers - Quest and Roleplay Communities - Multi-world Server Setups - Servers that want immersive physical mailboxes and GUI mail delivery - Servers that want API, command, or menu-driven mail integration with other plugins --- ![Mailbox Setup](https://github.com/Rismr1/MailboxGUI/blob/main/assets/mailboxsetupbanner.png?raw=true) ## Physical Mailbox Setup A standard player mailbox is built with: ```text Fence Post Normal Single Chest placed on top Sign attached to the front of the chest ``` Players can register a mailbox by right-clicking either the mailbox chest or the front sign. The sign displays: - Plugin name - Player name - Mailbox number ### Post Office Boxes Post Office Boxes are also supported: ```text Normal Single Chest Sign attached to the front of the chest ``` Post Office boxes are public mailbox access points for cities, towns, spawn areas, hubs, and shared post offices. --- ## Compatibility ### Supported Server Versions ```text Spigot/Paper 1.18.2 through 1.21.11 Spigot/Paper 26.1.x Spigot/Paper 26.1.1 Spigot/Paper 26.1.2 ``` ### 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 / 26.1.1 / 26.1.2 should use the Java version required by that server build. ### Optional Dependencies - **Vault** — required for money mail and COD package payments. - **Citizens** — optional for Post Office NPCs. - **Dynmap** — optional for map markers. - **PlaceholderAPI** — optional for `%mailboxgui_*%` placeholders. > **Important Dynmap Note:** Dynmap marker support is not currently supported on 26.1.x / 26.1.1 / 26.1.2 because Dynmap does not currently provide compatible builds for those versions. MailboxGUI itself still works without Dynmap. Mailboxes, inboxes, packages, letters, money mail, Post Office boxes, NPC access, storage, and admin tools can still function normally without Dynmap markers. > **Important:** Multiverse-Core is not required. MailboxGUI uses Bukkit world/location handling and includes safe checks for missing or unloaded worlds. --- ![Plugin Features](https://github.com/Rismr1/MailboxGUI/blob/main/assets/pluginfeaturesbanner.png?raw=true) ## Plugin Highlights ### Player Mailboxes - Register physical mailbox locations. - Multiple mailboxes per player. - Configurable mailbox limit. - Front sign registration support. - Optional floating new-mail paper icon visible only to the mailbox owner. ### Letters - Send player-written letters. - Offline delivery support. - Player reply flow. - Admin/server letters. - Polished letter lore. ### Packages - Send item packages through the GUI. - Configurable package size. - Preserves Bukkit item metadata. - Supports custom names, lore, enchantments, potions, player heads, and custom plugin items. - Supports saved item templates for command-based package delivery. - Prevents nested package abuse. - Optional loaded shulker protection. ### Package Experience - Add XP directly into packages. - XP appears as a Bottle o’ Enchanting. - XP uses a real package slot. - Any click to claim package XP. - Old package XP lore is upgraded through the mailbox data upgrade system. - Admin packages can include XP without using admin personal XP. ### Cash-On-Delivery Packages - Send COD packages with Vault economy. - Recipients preview before paying. - Accepted and returned COD package states. - Admin/console COD packages can be sink-cost or return payment to a selected player. - `/mba scod r:` can return COD payment and declined package contents to the selected return player. ### Money Mail - Send money directly through the mailbox system. - Requires Vault economy support. - Player and admin/server money mail. - Configurable admin/server money sender name. ### Recipient Selection - Online Players / All Players / Offline Players filters. - Default filter is Online Players. - Type Player Name checks MailboxGUI data and can import server-known players from world playerdata. - Case-insensitive typed recipient search. - Admin multi-recipient typed input fails safely if any recipient has never joined the server. ### Post Office Boxes & NPCs - Public Post Office boxes for towns, cities, and spawn hubs. - Citizens Post Office NPC support. - Works without Citizens if NPCs are not needed. ### Notifications - Offline mail delivery summary. - Simple / Advanced / Off offline summary modes. - Online delivery notification toggle. - Floating new-mail paper icon support. ### PlaceholderAPI - Optional PlaceholderAPI hook. - Adds `%mailboxgui_*%` placeholders for mailbox status, pending mail, storage type, delayed mail queue count, and more. - MailboxGUI still works normally without PlaceholderAPI. --- ## API & Plugin Integration MailboxGUI 4.1.x includes a public API for other plugins to send mail through MailboxGUI. The API can send: - Letters - Regular packages - Cash-On-Delivery packages - Money mail - Multiple-recipient mail - Custom sender display names - Delayed mail - Full Bukkit `ItemStack` package contents The new admin/console commands are also useful for plugin integrations that run console commands. This makes MailboxGUI easier to connect with shops, quests, rewards, menus, crates, voting systems, and custom server workflows. Full API usage and developer documentation are available on the wiki. --- ## Storage System MailboxGUI supports: ```text YAML SQLITE MYSQL ``` ### Fresh Installs Fresh installs default to SQLite. SQLite database location: ```text plugins/MailboxGUI/data/data.db ``` ### Legacy Upgrades Older versions used: ```text plugins/MailboxGUI/mailboxdata/.yml plugins/MailboxGUI/postofficedata/mailboxes.yml plugins/MailboxGUI/mailboxsounds/sounds.yml ``` When upgrading from 3.1.2 or older: - Legacy YAML data is detected automatically. - Existing legacy installs stay on YAML storage. - Old data is copied into the new data structure. - Old mail items are upgraded safely. - Old mail without timestamps receives a shared startup conversion timestamp. Existing 4.0.2 and 4.1.0 mail data remains compatible with 4.1.x. No mailbox reset is required. ### Storage Conversion Admins can convert storage with: ```text /mailbox admin convert to /mba convert to ``` Conversion includes: - Source validation. - Same-type conversion blocking. - Backup creation. - Target cleanup before copy. - Config update only after successful conversion. - Mailbox/Post Office data reload after conversion. - Persistent delayed mail conversion. - Item template conversion. - MySQL connection/login/table validation before switching. ### Persistent Delayed Mail & Item Templates Delayed mail now survives server shutdowns and restarts. This includes: - Player letter delay - Player package delay - API-created delayed mail - Admin/console command delayed mail Delayed mail and item templates follow the active storage backend: ```text YAML SQLITE MYSQL ``` Saved item templates are also included in storage conversion and backups. ### MySQL Safety If MySQL fails during startup, MailboxGUI logs a visible error and falls back to SQLite so the plugin can continue loading safely. --- ## Admin Tools Highlights ### Server Mail Tools - Send admin/server letters. - Send admin/server packages. - Send admin/server money mail. - Send packages with XP. - Send COD packages. - Send to all players, online players, or selected recipients. ### Admin / Console Sending Tools - Send raw letters, packages, COD packages, and money mail from console. - Designed for admins, automation, and other plugins that run commands. - Supports multiple recipients, custom senders, delays, XP, templates, and COD return recipients. ### Item Templates - Save held items as reusable package templates. - Send custom items through package commands. - Supports enchanted items, written books, lore items, CustomModelData, and plugin-created item metadata. ### Inbox Management - Inspect player inboxes. - Remove individual mail. - Empty inboxes when needed. - Admin-safe inbox views and actions. ### Mailbox Management - Register mailboxes for players. - Unregister player mailboxes. - View registered mailboxes. - Manage loaded and unloaded mailbox entries safely. ### Post Office Management - Register Post Office boxes. - Remove Post Office boxes. - View registered Post Office boxes. - Set/remove Citizens Post Office NPCs. --- ## Screenshots ### Standard Registered Mailbox ![Standard Registered Mailbox](https://raw.githubusercontent.com/Rismr1/MailboxGUI/main/assets/gallery/mailbox-registered.png) ### Mailbox With New Mail Notification ![Mailbox With New Mail Notification](https://raw.githubusercontent.com/Rismr1/MailboxGUI/main/assets/gallery/mailbox-new-mail.png) ### Inbox With Mail ![Inbox With Mail](https://raw.githubusercontent.com/Rismr1/MailboxGUI/main/assets/gallery/inbox-with-mail.png) ### Letter Example ![Letter Example](https://raw.githubusercontent.com/Rismr1/MailboxGUI/main/assets/gallery/letter-example.png) ### City Post Office Boxes ![City Post Office Boxes](https://raw.githubusercontent.com/Rismr1/MailboxGUI/main/assets/gallery/post-office-boxes-city.png) --- ## Commands ### Player ```text /mailbox /mb /mailbox register /mailbox unregister ``` ### Admin ```text /mailbox admin /mba /mailbox admin tools /mba tools /mailbox admin register /mailbox admin unregister /mailbox admin import player [,] /mailbox admin convert to /mailbox admin reload ``` ### Admin / Console Sending Commands | Command | Purpose | | --- | --- | | `/mba sl [from] ''` | Send an admin/server letter. | | `/mba sp [from] ` | Send a package with vanilla items, XP, or templates. | | `/mba scod [from] [r:] ` | Send a COD package. `r:` controls COD payment return and declined-package return. | | `/mba sm [from] ` | Send admin/server money mail. | Examples: ```text /mba sl Rismr1 Server 'Welcome to the server' /mba sp Rismr1 ServerShop t:starter_sword:1 xp:100 /mba scod Rismr1 Market 1000 r:Seller t:rare_pickaxe:1 /mba sm Rismr1 Rewards 250 ``` ### Item Template Commands ```text /mba itsave /mba itlist [page] /mba itdelete /mba itgive [player] ``` Full command form also works: ```text /mba itemtemplate save /mba itemtemplate list [page] /mba itemtemplate delete /mba itemtemplate give [player] ``` Full command details are available on the wiki. --- ## Permissions ### Core Permissions ```text mailboxgui.player.use mailboxgui.player.postoffice.npc mailboxgui.player.postoffice.pobox mailboxgui.admin mailboxgui.admin.reload mailboxgui.admin.import mailboxgui.admin.convert mailboxgui.admin.send mailboxgui.admin.itemtemplate mailboxgui.admin.tools.* ``` ### Admin Send Permissions ```text mailboxgui.admin.send.letter mailboxgui.admin.send.package mailboxgui.admin.send.cod mailboxgui.admin.send.money ``` ### Item Template Permissions ```text mailboxgui.admin.itemtemplate.save mailboxgui.admin.itemtemplate.delete mailboxgui.admin.itemtemplate.list mailboxgui.admin.itemtemplate.give ``` ### Admin Tool Categories ```text mailboxgui.admin.tools.sendmail.* mailboxgui.admin.tools.postoffice.* mailboxgui.admin.tools.inboxcheck.* mailboxgui.admin.tools.managemailbox.* ``` Full permission details are available on the wiki. --- ## Installation 1. Place the MailboxGUI jar into your server plugins folder. 2. Start the server once. 3. Configure the generated files. 4. Restart the server or run: ```text /mailbox admin reload ``` Fresh install file structure: ```text plugins/MailboxGUI/ ├── config.yml ├── sounds.yml ├── language/ └── data/ ├── data.db ├── playerdata/ └── postofficedata/ YAML storage can also use: ├── itemtemplates.yml └── delayed-mail.yml ``` For detailed setup, configuration, storage conversion, API usage, and command guides, use the wiki: https://plugins.imagine-craft.net/mailboxgui/wiki/ --- ## Issues & Support MailboxGUI is an active plugin, and support is quick. If you need help, find a bug, or want to request a feature, use Discord or open a GitHub ticket. **Discord Support Server:** https://discord.gg/67RsHugqBp **GitHub Issues:** https://github.com/Rismr1/MailboxGUI/issues Please include: - Plugin version. - Server version. - Java version. - Storage type: YAML, SQLite, or MySQL. - Console errors if available. - Whether Vault, Citizens, Dynmap, or PlaceholderAPI are installed. - If using 26.1.x / 26.1.1 / 26.1.2, mention that Dynmap marker support is currently unsupported on those versions. --- ## Planned Feature Updates - Additional compatibility testing may be added based on demand. - API/wiki examples for plugin integrations, DeluxeMenus system shops, and command-based automation will continue to expand. - Dynmap support for 26.1.x / 26.1.1 / 26.1.2 will be reviewed when Dynmap releases compatible builds. - Feature requests can be submitted through Discord or GitHub Issues. --- **Author:** Rismr1

Rismr1

Rismr1's Plugins

MailboxGUI by Rismr1

Rismr1's Organizations

Stars

Watching

MailboxGUI by