Welcome to the Hangar Open Beta. Please report any issue you encounter on GitHub!
Avatar for Rismr1
Avatar for Rismr1
Rismr1 /

MailboxGUI

MailboxGUI Package (COD Support), Letter, and Money Mailbox sending GUI interface System

Report MailboxGUI?

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 stronger plugin integration tools. Other plugins can integrate with MailboxGUI through the API or by running admin/console sending commands for more flexible mail delivery.

4.1.x Update Highlights

  • Added a public API for plugin integrations.
  • Added admin/console sending commands for letters, packages, COD packages, and money mail.
  • Added item templates for sending custom items, enchanted items, written books, lore items, and plugin-created items through commands.
  • Added PlaceholderAPI support with %mailboxgui_*% placeholders.
  • Added persistent delayed mail that survives server restarts.
  • Added delayed mail support for YAML, SQLite, MySQL, and /mba convert.
  • Added better typed-recipient handling with server playerdata auto-import.
  • Added COD return-recipient support with /mba scod r:<player>.
  • Added 4.1.1 storage polish for item templates, MySQL validation, and /mba convert coverage.

Support

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
  • Servers that want API, command, or menu-driven mail integration with other plugins

Mailbox Setup

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

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.
  • Supports saved item templates for command-based package delivery.
  • 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/console COD packages can be sink-cost or return payment to a selected player.
  • /mba scod r:<player> can return COD payment and declined package contents to the selected return player.

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 checks MailboxGUI data and can import server-known players from world playerdata.
  • Case-insensitive typed recipient search.
  • Admin multi-recipient typed input fails safely if any recipient has never joined the server.

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.

PlaceholderAPI

  • Optional PlaceholderAPI hook.
  • Adds %mailboxgui_*% placeholders for mailbox status, pending mail, storage type, delayed mail queue count, and more.
  • MailboxGUI still works normally without PlaceholderAPI.

API & Plugin Integration

MailboxGUI 4.1.x 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

The new admin/console commands are also useful for plugin integrations that run console commands. This makes MailboxGUI easier to connect with shops, quests, rewards, menus, crates, voting systems, and custom server workflows.

Full API usage and developer documentation are 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 new data structure.
  • Old mail items are upgraded safely.
  • Old mail without timestamps receives a shared startup conversion timestamp.

Existing 4.0.2 and 4.1.0 mail data remains compatible with 4.1.x. No mailbox reset is required.

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

Persistent Delayed Mail & Item Templates

Delayed mail now survives server shutdowns and restarts.

This includes:

  • Player letter delay
  • Player package delay
  • API-created delayed mail
  • Admin/console command delayed mail

Delayed mail and item templates follow the active storage backend:

YAML
SQLITE
MYSQL

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.

Admin / Console Sending Tools

  • Send raw letters, packages, COD packages, and money mail from console.
  • Designed for admins, automation, and other plugins that run commands.
  • Supports multiple recipients, custom senders, delays, XP, templates, and COD return recipients.

Item Templates

  • Save held items as reusable package templates.
  • Send custom items through package commands.
  • Supports enchanted items, written books, lore items, CustomModelData, and plugin-created item metadata.

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.

Screenshots

Standard Registered Mailbox

Standard Registered Mailbox

Mailbox With New Mail Notification

Mailbox With New Mail Notification

Inbox With Mail

Inbox With Mail

Letter Example

Letter Example

City Post Office Boxes

City Post Office Boxes

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

Command Purpose
/mba sl <recipients> [from] '<message>' Send an admin/server letter.
`/mba sp [from] <item:amount t:id:amount
`/mba scod [from] [r:] <item:amount t:id:amount
/mba sm <recipients> [from] <amount> Send admin/server money mail.

Examples:

/mba sl Rismr1 Server 'Welcome to the server'
/mba sp Rismr1 ServerShop t:starter_sword:1 xp:100
/mba scod Rismr1 Market 1000 r:Seller t:rare_pickaxe:1
/mba sm Rismr1 Rewards 250

Item Template Commands 

/mba itsave <id>
/mba itlist [page]
/mba itdelete <id>
/mba itgive <id> [player]

Full command form also works:

/mba itemtemplate save <id>
/mba itemtemplate list [page]
/mba itemtemplate delete <id>
/mba itemtemplate give <id> [player]

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 Send Permissions 

mailboxgui.admin.send.letter
mailboxgui.admin.send.package
mailboxgui.admin.send.cod
mailboxgui.admin.send.money

Item Template Permissions 

mailboxgui.admin.itemtemplate.save
mailboxgui.admin.itemtemplate.delete
mailboxgui.admin.itemtemplate.list
mailboxgui.admin.itemtemplate.give

Admin Tool Categories 

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

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

Information

CategoryGameplay
Published onApril 30, 2026
LicenseSource-Available
Downloads2
Stars0
Watchers0

Pinned Versions

Pages

Members

Avatar for Rismr1

Rismr1

Owner