MailboxGUI Banner

MailboxGUI

⚠️ CurseForge Update Notice

MailboxGUI will no longer receive future release updates on CurseForge.

This CurseForge page is kept as an informational/legacy listing only. For the latest MailboxGUI downloads, release updates, bug fixes, compatibility updates, and current documentation, please use the official active distribution pages:

Platform	Current Download Page
Modrinth	MailboxGUI on Modrinth
SpigotMC	MailboxGUI on SpigotMC
Official Website	MailboxGUI Downloads
Wiki	MailboxGUI Wiki

If you installed MailboxGUI from CurseForge, please switch to Modrinth or SpigotMC for current versions.

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, package experience, Cash-On-Delivery packages, item-currency COD 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.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 a major stable update for the 5.x network-ready release line. It added the new Book Letter system, expanded COD item-currency support, MailboxGUI API 5.1.0 updates, improved admin inbox tools, network-mode validation, and required compatibility support for Paper/Purpur 26.2.x.

Added Book Letters alongside Classic Paper Letters.
Added a 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.
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.

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 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 /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 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 network notification behavior.
Completed final 5.0.x language/configuration polish.

Current Download Pages

CurseForge is no longer used for new MailboxGUI releases. Please use one of these active pages for current downloads:

Platform	Current Download Page
Modrinth	MailboxGUI on Modrinth
SpigotMC	MailboxGUI on SpigotMC
Official Website	MailboxGUI Downloads

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, Book Letter usage, COD item-currency usage, 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 follow and download the project on Modrinth or SpigotMC. CurseForge is no longer the active update channel for MailboxGUI.

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

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 Hooks

Vault — required for money mail and Vault-money COD payments.
Vault2.0 — supported for custom currency names in money mail and Vault-money COD amount input.
Economy plugin — required alongside Vault for 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.

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

Classic Letters & Book Letters

Player-to-player Classic Letters.
New Book Letter type with real Book and Quill writing.
Protected temporary Book and Quill draft flow.
Sign-and-close Book Letter sending.
Offline delivery support.
Reply links for player-sent inbox Book Letters.
Back to Inbox links while reading.
Admin/server/API Book Letters.
Admin/server/API Book Letters do not include reply links.
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.
Updated package display colors for standard, COD, returned COD, accepted COD, and COD item-currency payment mail.

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.
COD packages can now use Vault money, item currency, XP, saved item templates, or combined prices.
Admin/API COD can use sink-cost behavior or optional return-recipient behavior.
r:<returnPlayer> controls both accepted COD payment return and declined package content return.
Economy display formatting can be customized or pulled from the Vault provider.
MailboxGUI 5.1.1 supports Vault2.0 custom currency names in money mail and Vault-money COD amount input.
Amount prompts normally accept plain numbers such as 12, but can also safely parse formatted currency text such as 12 Coins, 12 Dollars, $12, 12.50, 1,000, or a custom Vault2.0 currency name.

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.
DiscBridge payload support for Book Letters and COD item-currency payment mail.

Admin Tools

Send admin Classic Letters, Book Letters, packages, XP packages, COD packages, and money mail.
Manage player inboxes.
Read or delete Book Letters safely from admin inbox check.
Manage package mail from admin inbox check.
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.

Book Letters

MailboxGUI 5.1.0 adds Book Letters alongside Classic Paper Letters.

Players can send Book Letters through:

/mailbox
Send Mail
Letter
Book Letter
Select Recipient

Admins can send Book Letters through:

/mailbox admin tools
Send Mail
Letter
Book Letter

Book Letter behavior:

Uses a real Book and Quill writing flow.
Gives the sender a protected temporary Book and Quill.
Sends when the player signs and closes the book.
Typing cancel cancels the draft and restores the original hotbar item.
Logging out cancels the draft and restores the original hotbar item.
Player-sent inbox Book Letters include reply support.
Admin/server/API Book Letters do not include reply support.
When a Book Letter is taken from the inbox, inbox-only clickable actions are removed from the carried book copy.

Admin command:

/mba sla <recipient[,recipient2]|allplayers|onlineplayers> '<message>' --title <title> [--from <sender>] [--delay <seconds>]

COD Item Currency

MailboxGUI 5.1.0 expands COD package prices.

Supported examples:

100
diamond:4,gold_nugget:2,xp:100
100,diamond:3
t:rare_sword:1,xp:250

Supported price types:

Vault money
Item currency
XP currency
Saved item templates
Combined prices

COD item-currency payment mail uses a Purple Shulker Box display item.

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, distributed safety locks, and network notification payloads.

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, 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:

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

mode: NETWORK_NODE

DiscBridge does not run on Velocity itself.

DiscBridge Downloads

Platform	MailboxGUI-DiscBridge Page
SpigotMC	MailboxGUI-DiscBridge on SpigotMC
Modrinth	MailboxGUI-DiscBridge on Modrinth

API, Commands & Integrations

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

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:

Classic Letters
Book Letters
Packages
COD packages
COD item-currency packages
Money mail
Package XP
Delayed mail
Saved item templates
Custom sender names
Multiple recipients

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

API Maven dependency:

<dependency>
    <groupId>io.github.rismr1</groupId>
    <artifactId>mailboxgui-api</artifactId>
    <version>5.1.1</version>
    <scope>provided</scope>
</dependency>

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, Hong Kong Traditional 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.1.1 updates active bundled language files to file-version: 14 and adds messages_zh_hk.yml.

Chinese language files now include:

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.

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, Vault2.0, Citizens, Dynmap, PlaceholderAPI, or DiscBridge 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 on 26.1.x and 26.2.x depends on Dynmap’s own supported server versions.
Feature requests can be submitted through Discord or GitHub Issues.

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