Voxel Shop beta is live. Expect occasional bugs. Learn more  
MailboxGUI Free icon

MailboxGUI Free 6.1.0

GUI mailboxes with letters, packages, money mail, COD, custom GUIs, and scheduled delivery.

MailboxGUI-01-Header.png
MailboxGUI-02-Player-Exchange.gif
MailboxGUI-03-Inbox-And-Admin.gif
MailboxGUI-04-Mail-Examples-Row-1.png
MailboxGUI-05-Mail-Examples-Row-2.png
MailboxGUI is an advanced GUI mail system for Minecraft servers, built around physical mailbox access points or command-based inbox access. Let players use personal mailboxes, Public Access Mailboxes, or optional Citizens NPCs, or enable command access to open the mail GUI with /mb open. Choose the access style that suits your server.

Send letters, packages containing up to 28 item stacks, experience, and money mail, with attached messages and convenient replies. Deliver quest rewards, shop orders, voting rewards, event prizes, auction payouts, and welcome kits through one mail system. Connect other plugins through the public developer API or automate deliveries with admin and console commands. Customizable GUIs, HEX colors, localization, scheduled mail, and admin tools help you make the system your own.

All features listed on this page are specifically for MailboxGUI Free.

Version Support

Platforms: Paper • Spigot • Purpur • Bukkit

Minecraft Version: 1.18.2–26.3

Storage: SQLITE (Default) • MYSQL • YAML

Languages: English • German • Spanish • French • Italian • Japanese • Korean • Dutch • Polish • Brazilian Portuguese • Russian • Swedish • Ukrainian • Simplified Chinese (Mainland China) • Traditional Chinese (Hong Kong SAR) • Traditional Chinese (Taiwan)

MailboxGUI Release Support

2.1.0–5.1.1
Support Status: Unsupported
Upgrade Information: For single-server use, upgrade to 6.1.0 Free. If you use network mode in 5.0.0–5.1.1, upgrade to 6.1.0 Premium to retain network features.

6.0.0–6.1.0 Free
Support Status: Supported
Upgrade Information: Single-server edition; no network features. Includes upgrade systems for older installations. Use 6.1.0 Free for the latest Free release. Back up your plugin folder and database before updating.

6.1.0 Premium
Support Status: Supported
Upgrade Information: Latest network mode edition. Use this edition when upgrading a 5.0.0–5.1.1 installation that uses network mode.

Features - v6.1.0

GUI Customization

• Customize your GUI experience with gui.yml.
• Customize navigation controls, fillers, recipient icons, mail appearances, and floating new-mail notification items.
• Use built-in materials, CustomModelData, supported modern item models, and optional ItemsAdder items.
• Keep built-in icon fallbacks when a configured appearance is unavailable.
• Let players choose resource-pack appearance preferences with /mb settings resourcepack on|off|auto.

GUI customization is optional. Enable it in configuration to generate and load gui.yml. MailboxGUI does not provide or force a client resource pack.

Player Mail System

• GUI mailbox inbox.
• Paper letters.
• Book letters.
• Standard packages with up to 28 content slots.
• Packages and COD packages with messages.
• Money mail through Vault.
• Money mail with messages.
• Cash-on-Delivery packages.
• COD support for Vault money, item currency, XP, and item templates.
• Delayed mail delivery.
• Mail expiration.
• Mail tracking with /mb track.
• Read-only mailbox checking with /mb check.
• New mail notifications.
• Configurable mailbox kit command with /mb kit.
• Player notification settings.

Admin Tools

• Admin Tools GUI.
• Shared Admin Inbox.
• Check Player Inbox.
• Clear player mailbox data with confirmation.
• Admin mail sending tools.
• Admin package creation.
• Admin COD package creation.
• Scheduled mail management.
• Mail purge and cleanup tools.
• Storage conversion tools.

API Integration

Connect other server plugins to MailboxGUI through its public developer API. MailboxGUI Free includes:

• Send paper letters, book letters, standard packages, COD packages, and money mail.
• Attach messages to packages and money mail, include package XP, and send up to 28 package item stacks.
• Configure recipients, sender names, delivery delays, expiration, and notification behavior.
• Query, filter, and paginate inboxes, with safe mail claim and deletion operations.
• Track deliveries, inspect delayed mail, and cancel queued deliveries.
• Create, manage, enable, disable, and run scheduled mail tasks.
• Read registered player mailboxes, Public Access Mailboxes, and Public Access NPCs.
• Preserve custom item data through package serialization and custom item codecs.
• Integrate custom notification providers and listen for mail sending, delivery, claim, deletion, expiration, and registration events.
• Report verified resource-pack load status for custom GUI appearances.
• Check API capabilities and receive structured operation results.

For setup, supported API methods, and integration examples, see the API Integration Guide.

Mailbox Styles - Personal + Public Access Mailboxes

• Chests and trapped chests — 1.18.2+.
• Barrels — 1.18.2+.
• Shulker boxes, including all colors — 1.18.2+.
• Droppers, dispensers, and ender chests — 1.18.2+.
• Chiseled bookshelves — 1.20+.
• Crafters — 1.21+.
• Copper chests, including oxidized and waxed variants — 1.21.9+.
• Shelves — 1.21.9+.

Personal and Public Access Mailboxes use the same supported styles. Public Access NPCs are available through Citizens, ideal for mail rooms, post offices, and public access points.

Mailbox registration supports regular wall signs and fence bases available on your server version. Hanging signs are not registration signs. Unsupported materials are safely ignored on older versions.

Scheduled Mail

Scheduled Mail lets server owners create automatic mail tasks from config.

Scheduled Mail Supports:

• Send date.
• Send time.
• Daily, weekly, monthly, and interval-style repeat behavior.
• Server or configured timezone.
• Expiration.
• Catch-up behavior after restart.
• Recipient groups such as all players with mailbox data.

Text Formatting and Styling

• Keep traditional color and formatting codes such as &6, &a, and &l.
• Use compact HEX colors such as ᆒDB, alongside existing expanded HEX formatting.
• Use supported visual MiniMessage formatting, including HEX colors, gradients, and text styles.
• Customize configurable messages, GUI titles, item names, lore, sender names, notifications, and server branding.
• Apply supported formatting to paper letters, book letters, package messages, and money mail messages.

PlaceholderAPI Integration

• Use optional PlaceholderAPI placeholders for mail counts, inbox capacity, delivery, expiration, registrations, kits, and notification preferences.

Commands and Permissions

Player commands require mailboxgui.player.use. Additional permissions and settings are listed below; configuration paths refer to config.yml. Enabled world restrictions still apply.

The mail-sending command is /mb send . Choose the type you want to send.

Player Commands

/mb or /mb help
Permission: mailboxgui.player.use
Requirement / Action: Show command help.

/mb open
Permission: mailboxgui.player.open
Requirement / Action: Enable mailbox.command-open.enabled; opens your mailbox.

/mb guide
Permission: mailboxgui.player.use
Requirement / Action: Show the mailbox setup guide.

/mb register / /mb unregister
Permission: mailboxgui.player.use
Requirement / Action: Register or unregister a personal mailbox through selection.

/mb check
Permission: mailboxgui.player.use
Requirement / Action: Read-only check; mailbox.mailbox-check-command.setting selects GUI or text.

/mb track
Permission: mailboxgui.player.use
Requirement / Action: Requires mailbox.mail-tracking.enabled; shows queued delayed mail.

/mb kit [kitname]
Permission: mailboxgui.player.kit
Requirement / Action: Requires mailbox.kit.enabled and an enabled, supported kit; configured claim limits apply.

/mb send letter
Permission: mailboxgui.player.lettercommandsend
Requirement / Action: Enable enabled and player-command-send.enabled under letter.paper-letter and/or letter.book-letter.

/mb send package
Permission: mailboxgui.player.packagecommandsend
Requirement / Action: Requires package.enabled and package.player-command-send.enabled.

/mb send money
Permission: mailboxgui.player.moneycommandsend
Requirement / Action: Requires money.enabled, money.player-command-send.enabled, Vault, and a compatible economy plugin.

/mb settings
Permission: mailboxgui.player.use
Requirement / Action: View player settings and notification options.

/mb settings resourcepack
Permission: mailboxgui.player.use
Requirement / Action: Requires gui-customization.enabled; manual preferences are available when gui-customization.require-automatic-detection is false.

/mb settings discord
Permission: mailboxgui.player.discord
Requirement / Action: Requires DiscBridge Free and DiscordSRV; an administrator must enable DiscBridge player commands after setup checks.

Admin Commands

mailboxgui.admin grants the common admin permissions below. Players also need mailboxgui.player.use; individual tool actions may have additional permissions.

/mba or /mba help
Permission: Any applicable admin permission
Requirement / Action: Show the available admin commands.

/mba tools
Permission: mailboxgui.admin or mailboxgui.admin.tools.*
Requirement / Action: Open Admin Tools; individual actions have their own permissions.

/mba reload
Permission: mailboxgui.admin.reload
Requirement / Action: Reload configuration and language files; command-syntax changes require a restart.

/mba convert
Permission: mailboxgui.admin.convert
Requirement / Action: Show storage conversion options; back up your files and database first.

/mba scheduledmail
Permission: mailboxgui.admin.scheduledmail
Requirement / Action: Manage configured tasks; reload, run, and management actions have separate child permissions.

/mba admininbox
Permission: mailboxgui.admin.admininbox.open
Requirement / Action: Open the Shared Admin Inbox; claiming and management actions have separate permissions.

/mba updatecheck
Permission: mailboxgui.admin.update
Requirement / Action: Check release information; requires internet access.

/mba update
Permission: mailboxgui.admin.update
Requirement / Action: Start the update workflow; requires internet access and a restart to load a staged update.

/mba discord
Permission: mailboxgui.admin.discord
Requirement / Action: Requires DiscBridge Free and DiscordSRV; show Discord administration help.

Localized syntax: Set locale.command-syntax.default before the plugin loads to register the selected language's syntax. English commands are always registered; help displays the selected syntax. Restart after changing this setting.

See the official wiki for full syntax, permission inheritance, and additional admin commands.

Installation

Basic Setup

1. Download the MailboxGUI Free jar from this listing.
2. Place the jar in your server's plugins folder.
3. Start the server once to generate files.
4. Stop the server.
5. Review and configure plugins/MailboxGUI/config.yml.
6. Start the server again.
7. Use /mb guide in game to learn how to build and register mailboxes.

For upgrades, always back up the full plugins/MailboxGUI folder and your database before updating.

GUI customization: Enable gui-customization.enabled and run /mba reload to generate/load gui.yml. MailboxGUI does not build, send, or force a client resource pack.

Java: Plugin bytecode requires Java 17 or newer; use the Java runtime required by your Minecraft server version. Folia support is not included.

Version upgrades: MailboxGUI 5.1.1 and older are no longer supported. MailboxGUI 6.0.0–6.1.0 Free does not include network features. For single-server use, update to 6.1.0 Free. If you use network mode in 5.0.0–5.1.1, update to 6.1.0 Premium, the latest network mode edition. Back up your plugin folder and database before updating.

Dependencies

The core mailbox system requires no additional plugins. Install optional integrations only for the features you want to use.

ItemsAdder
Needed For: Optional custom GUI appearances.
Download / Requirement: ItemsAdder

Vault + economy plugin
Needed For: Money mail, Vault-money COD packages, and economy payouts.
Download / Requirement: Vault plus any Vault-compatible economy plugin. XConomy Reload is a suggestion.

DiscBridge Free
Needed For: Optional Discord mail notifications.
Download / Requirement: MailboxGUI DiscBridge; pair DiscBridge 2.1.0 Free with MailboxGUI 6.1.0 Free.

DiscordSRV
Needed For: Required by DiscBridge for Discord connectivity and account linking.
Download / Requirement: Download DiscordSRV on Modrinth.

Citizens
Needed For: Optional Public Access NPCs for mail rooms, post offices, or public access points.
Download / Requirement: Citizens; physical Public Access Mailboxes work without it.

PlaceholderAPI
Needed For: Optional MailboxGUI placeholders; the expansion is included in the plugin.
Download / Requirement: PlaceholderAPI

Dynmap
Needed For: Optional personal and Public Access Mailbox map markers.
Download / Requirement: Dynmap; server-version restrictions apply below.

Dynmap compatibility: Markers are not supported on Paper/Purpur 26.1.x or 26.2.x. The core mail system still works on those versions; disable or avoid Dynmap markers on those builds.

External Services

MailboxGUI includes configurable update checks and an administrator-triggered update workflow using the ImagineCraft update service. These features require internet access; the core mailbox system does not require a successful update check. Automatic checks can be configured through updates.enabled and updates.check-on-startup in config.yml.

Anonymous usage metrics use bundled bStats and require internet access when enabled. Metrics can be disabled through plugins/bStats/config.yml.

Support

• Discord: Support server
• Wiki: MailboxGUI documentation

如果您需要中文帮助,咨询插件使用、配置及问题反馈,欢迎加入 ImagineCraft 插件 QQ 交流群。

QQ群号:101849876 · 群内联系人:AFK·落子无悔(飞机)

Contributors

• nice — Simplified Chinese and Traditional Chinese (Hong Kong) translations.
• De4d__ — Brazilian Portuguese translation and MailboxGUI's new icon and color formatting style.

Want to contribute? Join the Discord support server and post in Plugin Discussion. Rismr1 will respond to you. Translation contributions, bug reports, and feature suggestions are welcome!

Owned
Ready to download
This resource is already attached to your account. You can download the latest file any time.

mailbox

mail

gui

letters

packages

economy

cod

survival

roleplay