MailboxGUI Banner

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 improved storage conversion polish while keeping the YAML, SQLite, and MySQL storage system intact.

4.1.x Update Highlights

Public API for other plugins to send letters, packages, COD packages, and money mail through MailboxGUI.
Admin/console sending commands designed for plugin integrations, console automation, and system-shop workflows.
Item templates for sending custom items, written books, enchanted gear, lore items, and metadata-heavy items by command.
Persistent delayed mail so delayed API, command, letter, package, and money mail survives restarts.
PlaceholderAPI support for MailboxGUI status, inbox, package, storage, and delayed mail placeholders.
Better typed-recipient handling with automatic server-playerdata import for known players.
4.1.1 storage polish for item templates, MySQL validation, and /mba convert coverage.

Support Links

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

Mailbox Setup Banner

Physical Mailbox Setup

A standard player mailbox is built with:

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:

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

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 Banner

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.
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/API COD packages can act as sink costs.
Optional COD return-recipient support for API and /mba scod command integrations.

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 searches MailboxGUI playerdata and server-known playerdata.
Server-known players can be imported automatically when mail is sent.
Case-insensitive typed recipient search.

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.

API, Commands & Integrations

Public API for other plugins to send MailboxGUI mail directly.
Admin/console raw sending commands for command-based plugin integrations.
Supports custom sender names, multiple recipients, delay seconds, XP package content, COD, and money mail.
Item templates allow command integrations to ship saved custom items with metadata.
Item templates are included in YAML, SQLite, MySQL, and storage conversion.
Detailed API documentation is available on the wiki.

Storage System

MailboxGUI supports:

YAML
SQLITE
MYSQL

Fresh Installs

Fresh installs default to SQLite.

SQLite database location:

plugins/MailboxGUI/data/data.db

Legacy Upgrades

Older versions used:

plugins/MailboxGUI/mailboxdata/<uuid>.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 current 4.x data structure.
Old mail items are upgraded safely.
Old mail without timestamps receives a shared startup conversion timestamp.

Storage Conversion

Admins can convert storage with:

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

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 queue conversion.
Item template conversion.
MySQL connection/login/table validation before switching.

Persistent Delayed Mail & Item Templates

Delayed mail and item templates use the active storage backend:

YAML
SQLITE
MYSQL

Delayed letters, packages, money mail, API mail, and command-created mail can survive server shutdowns and restarts. 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.

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.

Commands

Player

/mailbox
/mb
/mailbox register
/mailbox unregister

Admin

/mailbox admin
/mba
/mailbox admin tools
/mba tools
/mailbox admin register <player>
/mailbox admin unregister
/mailbox admin import player <name1>[,<name2>]
/mailbox admin convert <YAML|SQLITE|MYSQL> to <YAML|SQLITE|MYSQL>
/mailbox admin reload

Admin / Console Sending Commands

These commands are useful for raw mail sending, console automation, DeluxeMenus-style system shops, and other plugins that execute commands to integrate with MailboxGUI.

/mba sl <recipients> [from] '<message>'
/mba sp <recipients> [from] <item:amount|t:id:amount|xp:amount> [...]
/mba scod <recipients> [from] <codPrice> [r:<returnPlayer>] <item:amount|t:id:amount|xp:amount> [...]
/mba sm <recipients> [from] <amount>

Examples:

/mba sl Rismr1 ICServices 'Welcome to the server'
/mba sp Rismr1 ServerShop t:starter_sword:1 xp:100
/mba scod Rismr1 ICServices 1000 r:Rismr1 t:rare_pickaxe:1
/mba sm Rismr1 VoteRewards 250

Supported send-command features:

Multiple recipients with comma-separated names.
Optional custom sender display name.
Optional delayed delivery with --delay <seconds>.
XP package content with xp:<amount>.
Saved item templates with t:<id>:<amount>.
COD return-recipient support with r:<player>.
Automatic server-known playerdata import for valid recipients.

Full command details are available on the wiki.

Permissions

Core Permissions

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 Tool Categories

mailboxgui.admin.tools.sendmail.*
mailboxgui.admin.tools.postoffice.*
mailboxgui.admin.tools.inboxcheck.*
mailboxgui.admin.tools.managemailbox.*

Admin / Console Sending & Templates

mailboxgui.admin.send
mailboxgui.admin.send.letter
mailboxgui.admin.send.package
mailboxgui.admin.send.cod
mailboxgui.admin.send.money
mailboxgui.admin.itemtemplate
mailboxgui.admin.itemtemplate.save
mailboxgui.admin.itemtemplate.delete
mailboxgui.admin.itemtemplate.list
mailboxgui.admin.itemtemplate.give

Full permission details are available on the wiki.

Installation

Place the MailboxGUI jar into your server plugins folder.
Start the server once.
Configure the generated files.
Restart the server or run:

/mailbox admin reload

Fresh install file structure:

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, and usage 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