?
Host a server
Modrinth App
Sign in
ModsPluginsData PacksShadersResource PacksModpacksServers
Settings
MailboxGUI

MailboxGUI

A complete GUI-based mail system for Minecraft servers with physical mailboxes, letters, packages, Cash-On-Delivery, package experience, money mail, Post Office boxes, NPC support, offline delivery, admin tools, and YAML/SQLite/MySQL storage.

74
1
74
1

Compatibility

Minecraft: Java Edition

26.1.x
1.21.x
1.20.x
1.19.x
1.18.2

Platforms

Links

Report issues View source Visit wiki Join Discord server
Donate on PayPal

Tags

Creators

Details

Published last month

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, Cash-On-Delivery 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, packages, public mail access, and mailbox gameplay available.

MailboxGUI 5.0.1 continues the 5.x network-ready release line with optional network mode for multi-backend server setups, including Velocity-style networks. Single-server setups are still fully supported and remain the default.

MailboxGUI 5.0.1 Highlights

MailboxGUI 5.0.1 is the Backend Access & Offline Admin Sends Update. It adds optional command-based mailbox access, a new offlineplayers admin recipient tag, 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 1.0.1 is the current recommended DiscBridge release for 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 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 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 network-mode warnings for update commands because each backend must be updated separately.
  • Added support for MailboxGUI-DiscBridge 1.0.0 network notification behavior.
  • Completed final 5.0.0 language and configuration polish.

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

  • Vault — required for money mail and COD package payments.
  • Economy plugin — required for actual economy transactions.
  • Citizens — optional for Post Office NPCs.
  • Dynmap — optional for map markers.
  • PlaceholderAPI — optional for %mailboxgui_*% placeholders.
  • MySQL/MariaDB — required only for network mode.
  • Redis — required only for network mode.

Important Dynmap Note: Dynmap marker support depends on Dynmap’s own server-version compatibility. 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.

Core Features

Physical Player Mailboxes

Players can register physical mailbox locations in the world.

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

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. New default signs use clearer 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. In MailboxGUI 5.0.1, 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:

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. New default signs use clearer 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.

Letters

  • Send player-written 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.

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.
  • 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.
  • Optional COD return recipient support for API and /mba scod.
  • Custom money display formatting to match the server economy style.

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:

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

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

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.0.1 Compatibility: MailboxGUI-DiscBridge 1.0.1 is the current recommended DiscBridge release for 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 Downloads

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

Storage System

MailboxGUI supports:

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:

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

Admins can also check the current storage mode with:

/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 letters.
  • Send admin/server packages.
  • Send admin/server money mail.
  • Send packages with XP.
  • Send COD packages.
  • Send to all players, online players, offline players, or selected recipients.
  • Inspect player inboxes.
  • 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:

/mailbox admin tools

Update commands:

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

  • Letters
  • Regular packages
  • Cash-On-Delivery 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.0.x includes delivery event metadata and network event support used by addon plugins such as MailboxGUI-DiscBridge.

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.

MailboxGUI 5.0.1 adds optional 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

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:

plugins/MailboxGUI/language/

MailboxGUI can automatically use a player's Minecraft client locale when supported.

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

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.

Author: Rismr1