promotional bannermobile promotional banner

MailboxGUI

MailboxGUI adds GUI-based letters, packages, COD packages, XP packages, and money mail for Spigot/Paper servers. Supports physical mailboxes, Post Office boxes, Citizens NPCs, Vault economy, Dynmap markers, languages, and 1.18.2–1.21.11 plus 26.1.x.
Download
mailbox-registered.png

mailbox-registered.png

mailbox-new-mail.png

mailbox-new-mail.png

inbox-with-mail.png

inbox-with-mail.png

letter-example.png

letter-example.png

post-office-boxes-city.png

post-office-boxes-city.png

Description

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

  1. Place the MailboxGUI jar into your server plugins folder.
  2. Start the server once.
  3. Configure the generated files.
  4. 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

The MailboxGUI Team

profile avatar
Rismr1
Owner
  • 1
    Projects
  • 18
    Downloads
Donate