Welcome to the Hangar Open Beta. Please report any issue you encounter on GitHub!
Avatar for Rismr1
Avatar for Rismr1
Rismr1 /

MailboxGUI

MailboxGUI Package (COD Support), Letter, and Money Mailbox sending GUI interface System

Report MailboxGUI?

MailboxGUI Banner

MailboxGUI

Advanced Mailbox, Package, Letter, Economy & Network Mail System

Spigot / Paper / Purpur 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, package experience, Cash-On-Delivery packages, and money mail through physical mailboxes, public Post Office boxes, Citizens Post Office NPCs, admin tools, commands, and a public API.

MailboxGUI is designed for survival, RPG, economy, roleplay, town/city, quest, multi-world, and networked backend servers that want a more immersive mail system than simple chat messages or direct item handoffs.

MailboxGUI 5.0.1 Highlights

MailboxGUI 5.0.1 is a focused backend access and admin-send update for the 5.x network-ready release line. It adds optional command mailbox access, offline-player admin targeting, updated language files, and keeps full compatibility with MailboxGUI-DiscBridge 1.0.0.

  • Added optional /mailbox open and /mb open command access.
  • Added mailbox.command-open.enabled, disabled by default.
  • Added mailboxgui.player.open permission for command-based mailbox access.
  • Added the offlineplayers recipient tag for /mba sl, /mba sp, /mba scod, and /mba sm.
  • Added network-aware offline player targeting for admin send commands.
  • Updated language files to file-version: 12.
  • MailboxGUI-DiscBridge does not need to be updated for this release. DiscBridge 1.0.0 works with MailboxGUI 5.0.1.
  • Continued support for all MailboxGUI 5.0.0 network mode features, including MySQL/MariaDB shared storage, Redis synchronization, network-aware admin tools, update commands, and DiscBridge integration.

Previous 5.0.0 Network Support Highlights

MailboxGUI 5.0.0 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 MailboxGUI Network Mode for multi-backend / Velocity-style server networks.
  • Added shared MySQL/MariaDB support for network mail data.
  • Added Redis-backed network sync for inbox refreshes, paper notifications, admin tools, reloads, presence, and safety locks.
  • Added network-aware 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 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 update warnings for network mode because each backend must be updated separately.
  • Added support for MailboxGUI-DiscBridge 1.0.0 network notification behavior.
  • Completed final 5.0.0 language/configuration polish.

Support & Documentation

GitHub:
https://github.com/Rismr1/MailboxGUI

Wiki:
https://plugins.imagine-craft.net/mailboxgui/wiki/

Discord Support:
https://discord.gg/kggbGwRt42

Issues / Feature Requests:
https://github.com/Rismr1/MailboxGUI/issues

MailboxGUI has detailed documentation on the official wiki, including setup guides, screenshots, command usage, permissions, storage conversion, economy setup, Post Office setup, API notes, network configuration, DiscBridge setup notes, and troubleshooting.

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, please consider starring the project on Hangar. Feedback and reviews help other server owners discover the project and support 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 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 

Spigot/Paper/Purpur 1.18.2 through 1.21.11
Spigot/Paper/Purpur 26.1.x
Spigot/Paper/Purpur 26.1.1
Spigot/Paper/Purpur 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 Hooks

  • Vault — required for money mail and COD payments.
  • Economy plugin — required alongside Vault for economy transactions.
  • Citizens — optional for Post Office NPCs.
  • Dynmap — optional for map markers on supported versions.
  • PlaceholderAPI — optional for MailboxGUI placeholders.
  • MySQL/MariaDB — required only for network mode.
  • Redis — required only for network mode.

Dynmap Note: Dynmap marker support depends on Dynmap's own server-version compatibility. MailboxGUI itself still works without Dynmap.

Multiverse-Core Note: Multiverse-Core is not required. MailboxGUI uses Bukkit world/location handling and includes safe checks for missing or unloaded worlds.

Physical Mailboxes & Public Access Points

MailboxGUI is built around physical interaction points such as registered mailboxes, public Post Office boxes, and Citizens Post Office NPCs. In MailboxGUI 5.0.1, servers can also enable optional command-based mailbox access with /mailbox open or /mb open for backend servers or network setups where physical access points are not available.

Player Mailboxes

A standard player mailbox uses:

Fence Post
Normal Single Chest OR Barrel placed on top
Sign attached to the front face of the chest/barrel

Players register the mailbox and use it as their personal mail access point. Multiple mailboxes per player are supported and configurable.

Valid player mailbox notes:

  • The container must be a single chest or barrel.
  • Double chests are not valid mailboxes.
  • Trapped chests are not valid mailboxes.
  • The sign must be attached to the front face of the container.
  • Existing chest mailbox setups continue working normally.
  • Barrel mailboxes support the floating paper new-mail notification.

Post Office Boxes

Post Office boxes are public mailbox access points. They are not assigned to one player. Any permitted player can open a public Post Office box to access their own MailboxGUI mail menu.

A public Post Office box can use:

Normal Single Chest OR Barrel
Sign attached to the front face of the chest/barrel
No fence-post base required

Post Office boxes are shared access points, not shared inventories. Opening one shows the opening player's own personal MailboxGUI mail menu.

Post Office NPCs

Citizens NPCs can be marked as Post Office NPCs. Players right-click the NPC to access mail. Citizens is optional.

Plugin Highlights

Letters

  • Player-to-player written letters.
  • Admin/server letters.
  • Offline delivery support.
  • Reply flow support.
  • Polished lore and timestamps.

Packages

  • Send item packages through GUI mail.
  • Configurable package size.
  • Preserves item metadata, names, lore, enchantments, potions, heads, and plugin-created custom items.
  • Blocks nested package abuse.
  • Optional loaded shulker protection.

Package Experience

  • Add XP directly into packages.
  • XP appears as a Bottle o' Enchanting item.
  • XP uses a real package slot.
  • Players can claim package XP from received packages.
  • Admin/API packages can include XP without using admin personal XP.

Money Mail & COD Packages

  • Money mail and COD packages work through Vault economy.
  • Players can send money mail when enabled.
  • COD packages let recipients preview before paying.
  • COD supports accepted/returned package states.
  • Admin/API COD can use sink-cost behavior or optional return-recipient behavior.
  • Economy display formatting can be customized or pulled from the Vault provider.

Economy Optional Design

MailboxGUI works without Vault or an economy plugin. On non-economy servers, money and COD options are automatically hidden, creating a clean letters-and-packages mail system.

Recipient Selection

  • Online / All / Offline player filters.
  • Typed recipient search.
  • Case-insensitive lookup.
  • Server-known playerdata auto-import for players who have joined before.
  • Network-aware recipient lookup when network mode is enabled.
  • Admin recipient tags for allplayers, onlineplayers, and offlineplayers.

Notifications

  • Offline mail summaries.
  • Online delivery alerts.
  • Player-controlled online mail sound alerts.
  • Floating new-mail paper icon support.
  • Barrel mailbox paper notification support.
  • /mailbox check for new unchecked mail counts.

Admin Tools

  • Send admin letters, packages, XP packages, COD packages, and money mail.
  • Manage player inboxes.
  • Register/unregister player mailboxes.
  • Register/remove public Post Office boxes.
  • Set/remove Citizens Post Office NPCs.
  • Save and use item templates for custom package rewards.
  • Network-aware mailbox and Post Office management.
  • Manually check and stage plugin updates with admin update commands.

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

Velocity Note: 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:

MySQL/MariaDB shared storage
Redis
Unique server-id per backend
Same MailboxGUI version on every backend

Redis is used for cross-server refreshes, player presence, inbox state updates, paper notification updates, admin tool sync, reload requests, and distributed safety locks.

Single-server servers should leave network mode disabled.

For full network 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, and mail checks sync across backend servers so signs, paper notifications, and GUI state refresh correctly.

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:

/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.

It can send Discord notifications when MailboxGUI mail is delivered.

MailboxGUI 5.0.1 Compatibility: MailboxGUI-DiscBridge does not need to be updated for this release. MailboxGUI-DiscBridge 1.0.0 works with MailboxGUI 5.0.1.

Features include:

  • Discord DMs for eligible individual mail.
  • Channel notices for admin/API mass mail.
  • Support for letters, packages, COD packages, 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.

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:

mode: NETWORK_NODE

DiscBridge does not run on Velocity itself.

DiscBridge Download

SpigotMC:
https://www.spigotmc.org/resources/mailboxgui-discbridge-discordsrv-mail-notifications-for-mailboxgui.135557/

API, Commands & Integrations

MailboxGUI includes a public API and command-based sending tools for server automation and plugin integrations.

MailboxGUI 5.0.1 adds optional player command mailbox access:

/mailbox open
/mb open

This feature is disabled by default and can be enabled with:

mailbox:
  command-open:
    enabled: true

Required permissions:

mailboxgui.player.use
mailboxgui.player.open

Useful for:

  • DeluxeMenus-style reward shops
  • Quest reward delivery
  • Vote reward delivery
  • Server shop deliveries
  • Event rewards
  • Admin automation
  • Other plugins that need to send mailbox mail

API and command integrations can send:

  • Letters
  • Packages
  • COD packages
  • Money mail
  • Package XP
  • Delayed mail
  • Saved item templates
  • Custom sender names
  • Multiple recipients

MailboxGUI 5.0.x includes delivery event metadata and network event support used by addon plugins such as MailboxGUI-DiscBridge.

Full API and command details are available on the wiki:

https://plugins.imagine-craft.net/mailboxgui/wiki/

Storage System

MailboxGUI supports:

YAML
SQLite
MySQL

Fresh Installs

Fresh installs default to SQLite.

Legacy Upgrades

Older YAML installs are detected and kept on YAML unless the admin chooses to convert. This protects older servers from losing mail during upgrade.

Storage Conversion

Admins can check and convert storage with:

/mailbox admin convert current
/mailbox admin convert <YAML|SQLITE|MYSQL>

/mba convert current
/mba convert <YAML|SQLITE|MYSQL>

Storage conversion includes:

  • Source validation.
  • Same-type conversion blocking.
  • Backup creation.
  • Target cleanup before copy.
  • Config update only after successful conversion.
  • Manager reload after conversion.
  • Delayed mail queue conversion.
  • Item template conversion.
  • MySQL connection/login/table validation before switching.

Network Mode Note: In network mode, storage conversion is disabled to protect shared mail data. Convert to MySQL before enabling network mode.

Language Support

MailboxGUI includes active language files for:

English, German, Spanish, French, Swedish, Dutch, Italian, Japanese, Korean, Polish, Russian, Ukrainian, Simplified Chinese, and Traditional Chinese.

MailboxGUI can use a player's Minecraft client locale when supported. Language files are upgrade-aware and are designed to preserve customized text while adding new keys and updating old default text when needed.

MailboxGUI 5.0.1 updates bundled language files to file-version: 12.

Admin Update Commands

MailboxGUI includes website-powered update commands for admins:

/mailbox admin updatecheck
/mba updatecheck
/mba update
/mba update confirm

The update command downloads and stages a valid newer jar for the next restart.

Network Mode Note: When network mode is enabled, the update command only stages the update on the backend where it is run. Admins must stage and restart each backend separately.

Issues & Support

MailboxGUI is actively maintained, 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/kggbGwRt42

GitHub Issues:
https://github.com/Rismr1/MailboxGUI/issues

When reporting an issue, please include:

  • Plugin version
  • Server version
  • Java version
  • Storage type: YAML, SQLite, or MySQL
  • Whether network mode is enabled
  • Console errors if available
  • Whether Vault, Citizens, Dynmap, or PlaceholderAPI are installed
  • Whether the issue started after upgrading from an older MailboxGUI version

Roadmap Notes

  • API/wiki examples for plugin integrations, reward systems, system shops, and command-based automation will continue to expand.
  • Additional compatibility testing may be added based on demand.
  • Dynmap support depends on Dynmap's own supported server versions.
  • Feature requests can be submitted through Discord or GitHub Issues.

Author: Rismr1**

Information

CategoryGameplay
Published onApril 30, 2026
LicenseSource-Available
Downloads13
Stars0
Watchers0

Pinned Versions

Pages

Members

Avatar for Rismr1

Rismr1

Owner