MailboxGUI Wiki

What MailboxGUI Does

MailboxGUI adds a server mail system for Minecraft Spigot, Paper, and Purpur servers. Players can use mailboxes to send and receive letters, packages, money mail, and COD packages depending on the server settings.

Server owners can use MailboxGUI for player communication, roleplay, economy delivery, staff mail, rewards, and organized server systems that need more structure than chat or direct item handoffs.

MailboxGUI 5.1.1 keeps the single-server mailbox, classic letter, package, COD, money mail, Post Office, NPC, PlaceholderAPI, public API, and network workflows, and includes the 5.1.0 Book Letter and item-currency COD update plus Vault2.0 custom currency amount parsing and updated Chinese language files.

Network mode remains optional for multi-backend Velocity-style or BungeeCord-style server networks. When network mode is enabled, shared MySQL/MariaDB storage and Redis coordination are required for mail data, presence, refreshes, locks, and cross-server updates. Single-server setups are still fully supported and remain the default with network.enabled: false. Redis is required for network server mode, but not for normal single-server installs. MailboxGUI 5.1.1 targets Spigot/Paper/Purpur 1.18.2 through 1.21.11, plus 26.1.x and 26.2.x. MailboxGUI 5.1.0 or newer is required for 26.2.x because 5.0.1 does not support 26.2.x sign updating correctly. MailboxGUI 5.1.1 or newer is recommended for Vault2.0 custom currency support. MailboxGUI 5.1.1 uses config-version: 12, language file-version: 14, and mail data version 5.

Before You Install

Download MailboxGUI from one of the official platforms. The download page on this website links to SpigotMC, Modrinth, CurseForge, Hangar, and GitHub Releases. Voxel.shop is listed as coming soon while it remains under review.

Confirm the server version is supported by the current plugin release before installing. When installing or updating, use a full server stop and start instead of relying only on plugin reloads.

Use this wiki for setup details and the linked support/download areas when checking the current release, troubleshooting, or preparing server updates.

Recommended Dependencies and Hooks

• Vault: needed for economy features such as money mail, Vault-money COD payments, and paid post office actions when enabled.
• Economy plugin: required alongside Vault if the server wants economy-based mail features. Item-currency COD can remain available when Vault-money COD is unavailable, if enabled.
• Citizens: optional, used for NPC-based post office workflows if enabled.
• Dynmap: optional and can be used for map marker integration on supported server versions. Dynmap markers are not supported on 26.1.x or 26.2.x, but core MailboxGUI features still work.
• PlaceholderAPI: optional. Enables MailboxGUI's %mailboxgui_*% placeholders for scoreboards, holograms, tab lists, chat plugins, menus, and other PlaceholderAPI-compatible plugins. MailboxGUI runs normally without PlaceholderAPI, but placeholders are only registered when PlaceholderAPI is installed and enabled.
• MailboxGUI-DiscBridge: optional separate addon for DiscordSRV notifications. Use MailboxGUI-DiscBridge 1.1.1 or newer with MailboxGUI 5.1.1 for the updated zh_cn and new zh_hk language files. MailboxGUI-DiscBridge 1.1.0 or newer remains required for the MailboxGUI 5.1.0 Book Letter and COD payload updates.
• Storage: fresh single-server installs are designed around SQLite by default, while existing legacy YAML installs can remain on YAML safely during upgrade. MySQL/MariaDB is available for database-backed storage and is required for network mode.
• Redis: required only when MailboxGUI network mode is enabled.

Basic Install Flow

1. Stop the Minecraft server.
2. Place the MailboxGUI jar in the server plugins folder.
3. Start the server.
4. Let MailboxGUI generate its config, language, and data files.
5. Stop the server again before making larger config changes.
6. Configure storage, economy features, permissions, post offices, and language settings as needed.
7. Start the server again and test with a small group before public release.

First Things to Check

• Confirm the plugin enabled successfully in console.
• Confirm the MailboxGUI folder generated under plugins.
• Confirm the correct storage mode is being used.
• Confirm Vault and economy hooks if using money mail or Vault-money COD.
• Confirm players and admins have the permissions they need.
• Confirm physical mailbox setup works before announcing it to players.

Upgrading to 5.1.1

Back up the server before upgrading, but upgrading to 5.1.1 should not require deleting MailboxGUI data, config, or language files. MailboxGUI 5.1.1 uses config-version: 12, language file-version: 14, and mail data version 5.

The 5.1.0 mail data upgrade refreshes 5.0.1-and-older package mail so package, COD, XP, and item-currency package inbox items use the current preview and admin management lore.

The 5.1.1 language upgrade can update old default zh_cn text to the new contributed translation while preserving server-owner custom edits. It also adds the Hong Kong Traditional Chinese file messages_zh_hk.yml.

Good First Admin Setup

Review config.yml and language files, set up permissions, and create or test one physical mailbox before opening the system to players.

• Test sending a letter.
• Test sending a package.
• Test Vault-money COD and money mail only after economy support is confirmed.
• Test item-currency COD separately if the server uses material, XP, or template prices.
• Review admin tools and post office settings.

Command Overview

MailboxGUI uses /mailbox as the main command, with /mb as a player-friendly alias and /mba as the admin-focused alias. The plugin also supports /mailboxgui as an alias through plugin.yml.

• Player commands require mailboxgui.player.use.
• Admin commands require mailboxgui.admin or the specific admin permission.
• Some admin commands can be used from console where the command source supports it.
• Button names and messages can vary if language files are customized.

Player Commands

• Player registration uses a valid physical mailbox structure.
• /mailbox open and /mb open are disabled by default and controlled by mailbox.command-open.enabled.
• Command-based mailbox access requires mailboxgui.player.use and mailboxgui.player.open.
• /mailbox open is intended for backend servers or network setups where players may not have physical mailbox, Post Office box, or Post Office NPC access.
• /mailbox unregister now opens a GUI with Selection Mode and Manage Personal Mailboxes.
• Selection Mode keeps the older physical right-click unregister flow.
• Manage Personal Mailboxes lets players remove their own registered mailboxes from a GUI.
• In network mode, personal mailbox management shows server, world, and status. In single-server mode, the server line is hidden.
• /mailbox guide explains chest/barrel mailbox setup and that public PO Boxes and Post Office NPCs are access points to the player's own mail.
• /mailbox check counts unchecked/new mail items.
• Economy-specific check categories only appear/count when economy support is available.
• Player commands require mailboxgui.player.use.

Admin Dashboard and GUI Commands

• /mailbox admin by itself shows admin help, not the Admin Tools GUI.
• /mailbox admin tools opens the GUI.
• Admin GUI access depends on mailboxgui.admin.tools.* or the specific admin tool permissions.
• /mailbox admin clean deletes generated MailboxGUI backup files from old upgrades, YAML sync, language sync, and storage conversions after confirmation.
• /mailbox admin updatecheck uses the website release system and displays the official download link: https://plugins.imagine-craft.net/mailboxgui/download/.
• In Velocity-style or BungeeCord-style network setups, /mailbox admin update and /mailbox admin update confirm must be run on each backend server that has MailboxGUI installed, then each backend must be restarted. It is not a network-wide deployment command.
• Storage conversion is hidden/refused when network.enabled=true.
• Active mail data and active configuration files are not touched by backup cleanup.
• In-game players must type CLEAN in chat to confirm or cancel to cancel. Console can use clean confirm according to the plugin help text.
• Backup cleanup requires mailboxgui.admin.clean or mailboxgui.admin.

Player Data Import Commands

Manual playerdata import

/mailbox admin import player <name1>[,<name2>]
/mba import player <name1>[,<name2>]

• Imports player serverdata into MailboxGUI data for players who have already joined the server.
• Names are comma-separated.
• The player must exist in the main world playerdata, already exist in MailboxGUI data, or be available from the shared network player index in network mode.
• This is useful when an admin wants to prepare MailboxGUI data for players before they interact with mailboxes.
• MailboxGUI uses auto-import in typed recipient and admin command send flows where a player has joined the server before.
• In network mode, run /mba networkindex on relevant backends first so import can find players from the shared network player index.
• After indexing, /mailbox admin import player <name> can create full MailboxGUI player data from shared network-indexed UUID/name information.
• Local fallback/import reads the first loaded world's playerdata folder.

Storage Conversion Commands

Storage conversion

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

Examples:

/mailbox admin convert SQLITE
/mba convert MYSQL
/mba convert YAML

Current storage:

/mailbox admin convert current
/mba convert current

• Requires mailboxgui.admin.convert or mailboxgui.admin.
• current shows active storage backend while network mode is disabled.
• Target conversion converts from the active backend to the selected backend.
• Same-target conversion is refused.
• Backups are created before overwriting target storage.
• Conversion backups are stored under plugins/MailboxGUI/data/backups/storage-conversions/.
• Conversion to MYSQL validates MySQL first.
• Convert to MYSQL before enabling network mode.
• When network.enabled=true, all convert subcommands are hidden/refused because every backend must already be using shared MySQL/MariaDB storage.

Admin Send-Mail Commands

Admin send shortcuts

/mba sl <recipients> '<message>' [--from <sender>] [--delay <seconds>]

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

/mba sp <recipients> <item|t:id|xp...> [--from <sender>] [--delay <seconds>]

/mba scod <recipients> <price> [r:<returnPlayer>] <item|t:id|xp...> [--from <sender>] [--delay <seconds>]

/mba sm <recipients> <amount> [--from <sender>] [--delay <seconds>]

• sl sends a Classic Paper Letter, sla sends an admin/server Book Letter, sp sends a package, scod sends a Cash-On-Demand package, and sm sends money mail.
• Command send aliases can also be used through /mailbox admin when applicable.
• Recipients are comma-separated, or use allplayers, onlineplayers, or offlineplayers.
• allplayers and onlineplayers are supported by /mba sla.
• offlineplayers is supported by /mba sl, /mba sla, /mba sp, /mba scod, and /mba sm.
• offlineplayers sends to all known offline MailboxGUI recipients without sending to players currently online. In network mode, it uses MailboxGUI network-aware player tracking where available.
• In network mode, onlineplayers can include players on other backends through network presence.
• Use --from <sender> for the visible sender name.
• --delay uses seconds and queues persistent delayed mail.
• Admin command send uses API-backed send requests and RecipientPolicy.CREATE_IF_MISSING.
• Recipients are resolved from online players, MailboxGUI data, main-world server playerdata, and in network mode the shared network player index.
• In network mode, run /mba networkindex on legacy backends so old players can be found by typed/admin recipient lookup.
• If any recipient cannot be resolved/imported, the command fails and does not send partial mail.
• /mba scod supports r:<returnPlayer> or return:<returnPlayer> to opt into a real COD return/payment recipient.
• Admin/server/API Book Letters sent by /mba sla do not include Reply links.

Practical Admin Send-Mail Examples

These command-send workflows are useful for vote reward plugins, GUI shop/menu plugins, crate or reward plugins, quest plugins, compensation after rollbacks or bugs, event rewards, daily/login rewards, console automation, command blocks, server scripts, and other plugins that can run server commands.

Voting / vote reward examples

/mba sp %player% diamond:3 emerald:8 xp:250 --from VoteRewards
/mba sm %player% 500 --from VoteRewards
/mba sl %player% 'Thanks for voting! Your reward has been delivered by mail.' --from VoteRewards
/mba sla %player% 'Thanks for voting today!' --title Thanks --from VoteRewards --delay 30

• A vote reward plugin or vote listener command reward can mail item, XP, money, or message rewards instead of filling the player inventory.

Shop / GUI menu examples

/mba sp %player% t:starter_bundle:1 --from ServerShop
/mba sp %player% diamond_pickaxe:1 xp:500 --from ServerShop
/mba sm %player% 2500 --from ServerShop

• A menu or shop plugin can run these after purchase to deliver saved template items, item/XP kits, store credit, refunds, or bonus money by mail.

Crate / key reward examples

/mba sp %player% t:rare_reward:1 --from CrateRewards
/mba sl %player% 'You received a crate reward in your mailbox.' --from CrateRewards

• Crate or reward plugins can mail custom template rewards when inventory is full, or when rewards are granted while the player is offline.

Quest / RPG examples

/mba sp %player% t:quest_reward:1 xp:1000 --from QuestRewards
/mba sm %player% 750 --from QuestRewards
/mba sl %player% 'Quest complete! Your reward is waiting in your mailbox.' --from QuestRewards

• Quest plugins can mail reward bundles, XP, economy payouts, or story messages after a quest or story step.

Compensation / admin recovery examples

/mba sp allplayers diamond:16 emerald:16 xp:500 --from Compensation
/mba sm allplayers 1000 --from Compensation
/mba sl allplayers 'Thanks for your patience during maintenance. A compensation reward was sent to your mailbox.' --from ServerTeam

• Use these for server-wide compensation after downtime, rollback recovery, bugs, or maintenance.

Online-only event examples

/mba sp onlineplayers fireworks:16 cake:1 --from EventRewards
/mba sl onlineplayers 'The event reward has been sent to your mailbox!' --from EventRewards

• onlineplayers targets only players currently online, which is useful for live event rewards.

Offline recipient example

/mba sl offlineplayers 'Welcome to the server' --from ExampleServer --delay 10

• offlineplayers targets known MailboxGUI recipients who are not currently online, which is useful when an announcement or reward should wait for offline players only.

COD / shop-service examples

/mba scod %player% 1000 t:rare_pickaxe:1 --from Market
/mba scod %player% 1000 r:ShopOwner t:rare_pickaxe:1 --from Market
/mba scod allplayers ServerShop diamond:3,xp:250 r:Rismr1 template:event_key:1

• COD packages require the recipient to pay before claiming; use r:<returnPlayer> when a specific player should receive payment or declined contents.

Delayed delivery examples

/mba sl %player% 'Your timed reward will arrive soon.' --from DailyRewards --delay 60
/mba sla %player% 'Your daily news is in this book.' --title Daily --from DailyRewards --delay 60
/mba sp %player% t:daily_bundle:1 --from DailyRewards --delay 300

• Delayed mail is useful for timed rewards, scheduled events, or delayed quest rewards.

Multiple recipient examples

/mba sl player1,player2 'Your team reward has arrived.' --from EventRewards
/mba sla player1,player2 'Read page two for the team message.' --title Team --from EventRewards
/mba sp player1,player2 t:team_bundle:1 --from EventRewards

• Multiple named recipients are comma-separated.

Admin/server Book Letter examples

/mba sla Rismr1 'Read page two for the message.' --title Welcome --from ICServices
/mba sla allplayers 'Server news is on the next page.' --title Server News --from Server
/mba sla onlineplayers 'Thanks for playing today!' --title Thanks --from VoteRewards --delay 30

• /mba sla sends admin/server Book Letters and uses the existing admin letter-send permission path.

Admin Send-Mail Item Tokens

Package commands such as /mba sp and /mba scod support these item tokens.

Item token forms

material:amount
xp:amount
template:<id>:amount
t:<id>:amount

Examples

stone:64
diamond:3
xp:250
template:starter-kit:1
t:rare-sword:1

• Materials use Bukkit/Minecraft material names.
• xp:amount adds package experience.
• template:<id>:amount uses a saved item template.
• Package slot limits still apply.
• Nested MailboxGUI packages are blocked.
• Non-empty shulker boxes are blocked when configured.
• Oversized command packages are rejected based on configured package slot count.

Item Template Commands

Item template commands

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

Aliases:

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

Shortcut aliases:

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

• Saving requires holding the item in the player's main hand.
• Templates are used in admin command packages as template:<id>:amount or t:<id>:amount.
• Templates are stored in plugins/MailboxGUI/data/itemtemplates.yml.
• Give is useful for testing saved templates.
• Template IDs should follow the plugin's ID rules.

Command Permissions

• mailboxgui.player.use
• mailboxgui.admin
• mailboxgui.admin.reload
• mailboxgui.admin.import
• mailboxgui.admin.convert
• mailboxgui.admin.update for update checks, update preparation, and update confirmation
• mailboxgui.admin.networkindex
• mailboxgui.admin.clean
• mailboxgui.admin.send
• mailboxgui.admin.send.letter for /mba sl and /mba sla
• mailboxgui.admin.send.package
• mailboxgui.admin.send.cod
• mailboxgui.admin.send.money
• mailboxgui.admin.itemtemplate.*
• mailboxgui.admin.tools.*

See the Permissions section for the complete permission reference.

What Counts as a Physical Mailbox

A valid physical mailbox is one normal single chest or one barrel with a sign attached to the front face of the chest/barrel.

The single chest or barrel is the supported container and interaction point. The sign must be attached to the front face of the container, not the side, back, ground, or a nearby block. A fence post base is the classic visual build style, but MailboxGUI 5.0.0 validates the container/sign pair rather than requiring a fence block under the container.

Existing chest mailbox designs continue working. Barrels are an alternate supported container in MailboxGUI 5.0.0. Double chests and trapped chests are still invalid.

Personal mailboxes are private physical mailbox locations owned by a specific player. They are different from public Post Office boxes, which are shared access points to each player's own MailboxGUI menu.

Materials Needed

• 1 fence post or decorative base, optional but recommended for the classic mailbox look
• 1 single chest OR 1 barrel
• 1 sign
• Optional decoration blocks around it, as long as the valid chest/barrel and front sign remain accessible.

Step-by-Step Build

1. Optionally place a fence post or decorative base where the mailbox should stand.
2. Place one single chest or one barrel where players can reach it.
3. Attach the sign to the front face of the chest/barrel.
4. Keep the sign on the container face, not beside the container.
5. If using a chest, make sure it remains a single chest and is not converted into a double chest.
6. Finish any decoration around the mailbox after the core structure is correct.
7. Register/access through the front sign or container according to the server's permissions and supported flow.

Correct vs Incorrect Setup

Common mailbox build mistakes include:

• Using a double chest instead of a single chest or barrel.
• Using a trapped chest.
• Placing the sign on the ground instead of attaching it to the front face of the chest/barrel.
• Attaching the sign to the wrong side; MailboxGUI checks the front attached sign.
• Blocking access to the container or sign with decoration blocks.
• Building the mailbox in a protected region without the proper permission.

Player Usage

Once a mailbox is properly built and recognized by the server, players can use it to access mail features according to server settings. Available actions may include checking inbox mail, receiving letters, receiving packages, paying for COD packages, or interacting with post office systems depending on configuration.

Admin Notes

Admins should test one mailbox before allowing players to build many. Server protection plugins may affect whether players can place signs, place containers, or interact with mailboxes.

If a mailbox is not detected, verify the structure first before checking permissions or config. Keep a consistent mailbox design in public areas so players know what to look for.

• During registration, players and admins can right-click either the valid single chest/barrel or the front attached sign.
• MailboxGUI resolves the sign/container pair as long as the sign is attached to the front face of the chest/barrel.
• Paper new-mail notifications work with player barrel mailboxes.
• The current default player mailbox sign uses Personal Mail and Right Click.
• Number placeholders still exist for custom or older sign formats, but the default sign no longer displays a mailbox number.

What Letters Are

Letters are player-to-player written messages sent through the MailboxGUI system. They are useful for player communication, roleplay, town and server notices, staff replies, shop messages, and general mailbox-based communication.

Letters keep communication tied to the mailbox system instead of relying only on public chat or direct messages. Server settings and permissions control who can send, receive, reply to, or manage letters.

MailboxGUI 5.1.0 has two letter types: Classic Paper Letter and Book Letter. Classic Paper Letters use the older paper/lore style and the classic chat/GUI letter flow. Book Letters use a real temporary Book and Quill and are covered in their own section below.

Sending a Letter

1. Open /mailbox or a mailbox access point.
2. Choose Send Mail.
3. Choose Letter.
4. Choose Classic Letter or Book Letter.
5. For Classic Letter, select the recipient, write the classic message, then confirm and send.
6. For Book Letter, follow the temporary Book and Quill flow in the Book Letters section.
7. The recipient receives it in their mailbox inbox according to the server's enabled features and permissions.

Choosing a Recipient

Players may choose a recipient through the recipient selection interface. Depending on server configuration and the current plugin setup, recipient selection may include online, offline, or all-player filtering.

Typed recipient entry may also be available where enabled. The selected recipient determines where the letter is delivered. Typed name lookup can auto-import players from main-world playerdata when they have joined the server before. In network mode, typed recipient lookup can use the shared network index. Admins should run /mba networkindex on legacy backends so old players can be found.

Admin command and API letters can target created/imported recipient data through RecipientPolicy.CREATE_IF_MISSING where supported.

Writing the Message

The letter body is the message the recipient will read. Players should keep messages appropriate for the server rules.

Long messages may be shown across multiple lines depending on the plugin's formatting and GUI layout. Formatting and colors may depend on server configuration.

Classic Paper Letters continue to use the established paper/lore inbox item style. Book Letters are written and signed through the Minecraft book editor instead.

Receiving and Reading Letters

Received letters appear in the player's inbox. Opening a letter lets the player read the message and see who sent it.

Letter lore and details may include sender information and sent time when available. The inbox is designed to keep mail organized after players take, delete, or handle mail.

/mailbox check can report unchecked letters for the player.

Letter Actions

Depending on server permissions and configuration, available letter actions may include:

• Read or preview the letter.
• Reply directly to the sender where reply support is available.
• Take or keep the letter when the server allows players to claim a copy.
• Delete or remove the letter when it is no longer needed.

Replies

Letter replies help continue a conversation from the received letter. Reply options are useful because players do not need to manually reselect the original sender.

If the sender is no longer available or the mail data is outdated, server behavior may depend on plugin configuration and stored player data.

Book Letter reply uses the same temporary Book and Quill flow as a new Book Letter. The reply is not sent until the player clicks Sign and Close. Typing cancel during a Book Letter reply returns the player to the inbox rather than the Select Letter Type menu.

Admin and Server Notes

Admin and server letters may use configured server sender names. Staff can use MailboxGUI tools for server communication when enabled.

Troubleshooting Letter Issues

• The player does not have permission to send letters.
• The recipient has not joined before or is not known to the plugin, depending on server data.
• The player chose Book Letter but did not right-click the temporary Book and Quill to open the editor.
• Economy or post office settings may block sending if the server charges for mail actions.
• Inventory or mailbox access may be blocked by region protection.
• Server language or config changes may make button names look different from screenshots.
• Restart the server after major plugin or config updates instead of relying only on reloads.

What Book Letters Are

MailboxGUI 5.1.0 adds Book Letters as a second letter type alongside Classic Paper Letters. Classic Paper Letters use the existing chat/GUI text flow. Book Letters use a temporary Book and Quill so players can write multi-page signed-book mail.

Final Book Letters use page 1 as a MailboxGUI info/action page. Page 2 and later preserve the original pages the sender wrote in the Book and Quill.

• Page 1 is generated by MailboxGUI for sender, date, reply, and navigation actions.
• Page 2 is the sender's original Book and Quill page 1.
• Page 3 is the sender's original Book and Quill page 2.
• Page 4 and later continue the original written pages.

Player Book Letter Flow

1. Open /mailbox.
2. Choose Send Mail, then Letter.
3. Choose Classic Letter or Book Letter.
4. Choose Book Letter.
5. Select the recipient.
6. MailboxGUI places a temporary Book and Quill into the player's selected hotbar slot.
7. The player manually right-clicks the Book and Quill to write.
8. The player writes one or more pages.
9. The player clicks Sign.
10. The player enters a title.
11. The player clicks Sign and Close.
12. The Book Letter sends immediately.

Writing, Signing, and Canceling

While a Book Letter draft is active, MailboxGUI blocks other inventory, item, block, and entity interactions until the draft is sent or canceled. Done or Escape while editing saves progress and keeps the temporary Book and Quill. Typing cancel in chat cancels the draft, removes the temporary Book and Quill, restores the original hotbar item with all metadata, and returns the player to the proper menu.

The temporary Book and Quill is protected while the draft is active. It cannot be duped, moved, dropped, swapped, or kept after sending, canceling, or logging out. Logging out while writing acts like cancel: the temporary Book and Quill is removed and the original hotbar slot item is restored.

Reading and Reply Links

Page 1 of a received Book Letter shows From, Date, Back to Inbox, and the instruction to go to the next page to read the Book Letter. Player-sent Book Letters also include a clickable Reply link. Admin, server, and API Book Letters do not include Reply links.

• Player-sent page 1 includes MailboxGUI Book Letter title, From, Date, Reply, Back to Inbox, and the next-page instruction.
• Admin/server/API page 1 includes MailboxGUI Book Letter title, From, Date, Back to Inbox or Back to Player Inbox, and the next-page instruction.
• Admin/server/API Book Letters never include Reply.

Reading from the normal inbox includes Back to Inbox. When a Book Letter is taken from the inbox, Reply and Back to Inbox actions are removed from the carried book. Players cannot reply from a carried Book Letter outside the inbox context.

Admin Book Letters

Admins can send Book Letters from /mailbox admin tools through Send Mail, Letter, Book Letter. Admins then choose All Mailboxes, Online Mailboxes, or Select Recipient. The admin receives a temporary Book and Quill, manually right-clicks it to write, adds pages, clicks Sign, enters a title, and clicks Sign and Close to send immediately. Admin Book Letters never include Reply links.

/mba sla supports command/API-style Book Letter sending for admin/server delivery flows.

Cancel restores the original hotbar item and returns the admin to the admin letter type selection/admin send flow.

Admin Inbox Check

In admin inbox check, Book Letter items show Left-Click to Read and Right-Click to Delete. They should not show Shift-Left-Click to Take in admin inbox check. When an admin reads a player Book Letter, Reply is hidden and the book shows Back to Player Inbox.

Left-click opens the Book Letter read view. Right-click deletes the Book Letter from that player's inbox. Back to Player Inbox returns the admin to that player's inbox check page.

Internal Book Links

The clickable in-book Reply and Back links use internal MailboxGUI commands. Players should use the book links rather than typing those commands manually.

/mailbox bookreply <uuid>
/mailbox bookback
/mailbox adminbookback

These commands are internal clickable Book Letter commands, not normal user-facing command workflows.

What Packages Are

Packages let players send item deliveries through MailboxGUI. A package can contain Minecraft items placed into the package compose slots, and servers can also allow package experience if that feature is enabled.

Packages are useful for gifts, shop deliveries, staff rewards, roleplay mail, event rewards, and organized player-to-player item delivery. Package availability depends on server permissions and configuration.

Starting a Package

1. Open the mailbox or mail menu.
2. Choose Send Mail.
3. Click Send Package.
4. Select the mailbox owner or recipient in the Select Mailbox GUI.

Recipient selection may include online, all, or offline filtering and typed recipient entry depending on the current plugin setup and permissions. Typed names can auto-import players from main-world playerdata when they have joined before. In network mode, typed recipient lookup can use the shared network index. Admins should run /mba networkindex on legacy backends so old players can be found.

In current releases, the Send Mail GUI is economy-aware. If money mail is disabled or Vault/economy support is unavailable, the menu hides Money Mail and adjusts the Letter/Package positions. Package send lore also omits COD wording when COD is disabled or no COD payment option is available.

Create Package GUI

After choosing a recipient, the Create Package GUI opens. The main content area is where package items are placed, and the bottom row contains package controls.

• Confirm Package: sends the package.
• Add Experience: opens the experience amount prompt when package experience is enabled.
• Cash-On-Demand: opens COD setup when COD is enabled and at least one payment option is available. COD controls are hidden or disabled when COD is disabled or no COD payment option is available.
• Cancel: returns normal items and exits the compose flow.

Adding Items

Place regular items directly into the package content slots. The number of slots depends on package.size-in-rows: 1 row gives 7 slots, 2 rows gives 14 slots, and 3 rows gives 21 slots.

The current default config uses 3 rows, giving 21 content slots. Empty slots are allowed, but at least one normal item or package experience must be included before sending.

Package Experience

If enabled, players can add experience to a package. Clicking Add Experience closes the GUI and asks the player to type an experience amount in chat.

The player must have enough experience when sender withdrawal is enabled. The experience appears in the package as a special experience item.

• In the compose GUI, right-clicking the experience item removes it from the package.
• In a received package, the default experience item lore says &e&lAny click to claim.

Package Safety Rules

MailboxGUI blocks packages inside packages to prevent nesting. Servers can also block non-empty shulker boxes inside packages.

With the default configuration, loaded shulker boxes are blocked. If the sender cancels the package, normal items are returned to the sender inventory, and leftovers may drop naturally if inventory space is unavailable.

Sending the Package

Confirm Package creates the package mail item and delivers it to the recipient. Delivery is immediate by default.

Servers can configure package.delivery-delay-seconds to delay package delivery. If a delivery delay is configured, the sender receives a scheduled delivery message.

Admin command and API package sends can also set delivery delay. Command package item tokens support material:amount, xp:amount, template:<id>:amount, and t:<id>:amount. Item templates are for admin command package item specs, not normal player package GUI composition.

/mailbox check can report unchecked regular packages for the player.

Receiving Packages

Regular packages appear in the recipient's inbox. Normal package inbox entries show package information such as sender, sent time, contents size, and experience included when applicable.

Normal packages are opened from the inbox into the Package Contents GUI. COD package preview and payment behavior is different and is covered in the COD Packages section.

Package Contents GUI

The Package Contents GUI displays the package contents in the content slots. The recipient withdraws the items manually from the GUI.

There is not a separate "claim package" button for regular packages. The close button saves any remaining contents and returns the player to the inbox.

If the package is emptied, the package is removed from the inbox. If only some items are removed, MailboxGUI rebuilds and saves the package with the remaining contents.

Troubleshooting Package Issues

• The player does not have permission to use package features.
• Packages are disabled in config.
• The recipient does not have a registered mailbox or is not known to MailboxGUI.
• The package is empty.
• A MailboxGUI package was placed inside another package.
• A non-empty shulker box was placed in the package while loaded shulker boxes are blocked.
• The player does not have enough experience for package experience.
• Economy or COD support is unavailable when trying to use COD.
• Inventory space is limited when cancelling or withdrawing items.
• Region protection blocks mailbox or GUI interactions.
• Server language customization may make button names look different from screenshots.

What COD Packages Are

COD packages are Cash-On-Demand packages. They are package deliveries that require the recipient to pay a configured price before the package can be accepted and opened.

They are useful for player shops, trade deliveries, auction-style delivery, marketplace purchases, roleplay merchants, and staff-controlled delivery systems.

Requirements

• Package sending must be enabled.
• COD must be enabled in config with package.cash-on-demand.enabled.
• At least one COD payment option must be enabled: Vault money, item currency, or both.
• Vault and an economy plugin are required only for Vault-money COD prices. MailboxGUI 5.1.1 also supports Vault2.0 custom currency names for Vault-money COD amount input.
• Item-currency COD can use materials, XP entries, and saved item templates when package.cash-on-demand.item-currency is enabled.
• The sender and recipient must have the needed MailboxGUI access based on the server's permissions.
• The recipient must have the required money, items, and/or XP to accept the COD package.

COD Price Formats

MailboxGUI 5.1.0 added Vault money, item currency, XP currency, saved item templates, and combined COD prices. MailboxGUI 5.1.1 adds safer Vault2.0 custom currency amount parsing for Vault-money COD amount input. Separate price parts with commas when combining money with item, XP, or template requirements.

100
12 Coins
12 Dollars
$12
12.50
1,000
12 <custom Vault2.0 currency name>
diamond:4,gold_nugget:2,xp:100
100,diamond:3
t:rare_sword:1,xp:250

• 100 means a Vault/economy price of 100.
• Users should normally type a number like 12.
• MailboxGUI 5.1.1 can also safely parse formatted Vault-money COD input such as 12 Coins, 12 Dollars, $12, 12.50, 1,000, or 12 <custom Vault2.0 currency name>.
• diamond:4,gold_nugget:2,xp:100 means 4 diamonds, 2 gold nuggets, and 100 XP.
• 100,diamond:3 means 100 economy money plus 3 diamonds.
• t:rare_sword:1 uses a saved item template. template:rare_sword:1 is the longer form.

Setting a COD Price

1. Start a package normally.
2. Choose the recipient.
3. Add package contents.
4. Click the Cash-On-Demand button in the Create Package GUI.
5. Type the COD price in chat using a money, item, XP, template, or combined price format. For Vault money, normally type a number like 12.
6. Type off, none, or 0 to remove COD.
7. Type cancel to return without changing the COD value.
8. After setting a valid amount, the Create Package GUI reopens and shows the enabled COD price.
9. Click Confirm Package to send.

In the Create Package GUI, the COD control appears on the bottom row. If COD is unavailable, the GUI shows COD Disabled. If COD is available but off, the button shows Cash-On-Demand: Off.

In current releases, the COD button/control may be hidden or disabled when COD is unavailable. Vault money requires Vault/economy support; item-currency prices require item-currency COD to be enabled. MailboxGUI 5.1.1 cleans up chat input before parsing amount prompts and control words such as cancel and off.

Recipient Preview

Unpaid COD packages appear in the recipient inbox as Cash-On-Demand Package. Opening the package shows Package Preview so the recipient can see what is inside before paying. The preview shows the full COD price, including any money, item, XP, or saved template requirements.

The preview has Accept, Cancel, and Decline/Return controls. Cancel returns to the inbox without making a payment or returning the package.

If the required COD payment support becomes unavailable, unpaid COD package previews are blocked and the player is told COD is unavailable.

Accepting a COD Package

Accept checks the recipient's required payment sources. If the recipient cannot afford the COD price, the package remains unpaid. If the recipient can afford it, Vault money, required item stacks, and XP requirements are removed as needed.

COD accept/decline handling is blocked from stale previews if required payment support disappears after the preview was opened.

The unpaid COD package is replaced with an accepted COD package. The accepted COD package can then be opened like a package into the Package Contents GUI, where the recipient manually withdraws the items.

If the package contains experience, the accepted package allows that experience item to be redeemed normally.

Sender Payment

For player-origin COD packages, payment handling depends on package.cash-on-demand.send-reward-in-mail for Vault-money payments. If true, the sender receives the money as MailboxGUI money mail. If false, the money is deposited directly into the sender's economy account.

Item-currency COD payment mail is delivered as Cash-On-Demand Item Currency Payment and is represented by a Purple Shulker Box. It carries the payment items collected from the recipient.

Declining and Returned COD Packages

Decline/Return sends the package contents back to the original sender as a returned COD package. The recipient does not pay when declining.

The original sender receives a returned COD package in their inbox. Returned COD packages can be opened without payment.

For /mba scod, r:<returnPlayer> or return:<returnPlayer> opts into returning COD payment and declined package contents to that player. If no return recipient is set for admin/API COD packages, accepted payments and declined package contents use sink behavior. The API equivalent is setting senderUuid with returnCodPaymentToSender(true).

Admin and API COD

Admin command COD can send money-only, item-currency, XP, template, or combined COD packages. The price can be the first price token or can use p: / price: when the sender name needs to be unambiguous.

/mba scod Rismr1 ICServices 1000 r:Rismr1 template:rare_pickaxe:1 diamond:64
/mba scod Rismr1 ServerShop diamond:8,emerald:4 r:Rismr1 template:rare_pickaxe:1
/mba scod allplayers ServerShop diamond:3,xp:250 r:Rismr1 template:event_key:1

• r:<returnPlayer> controls both COD payment return and declined package content return.
• Without r:<returnPlayer>, admin/API COD packages use sink behavior for accepted payments and declined contents.
• Declined COD package contents return to the configured return recipient when one exists.
• Accepted item-currency COD payments are delivered as item payment mail.
• API COD uses codAmount(...) for Vault money and addCodItemCurrency(...) or codItemCurrencyContents(...) for item-currency payments.

Package Color System

Package Experience in COD Packages

COD packages may contain package experience if package experience is enabled. In the unpaid preview, experience shows special preview lore telling the player to accept the COD package before claiming XP.

After accepting, the accepted COD package opens like a package and the experience item can be redeemed with right-click or Shift-left-click.

Troubleshooting COD Packages

• COD button shows disabled because COD is disabled or no COD payment option is available.
• Vault-money COD requires Vault and a compatible economy plugin.
• Item-currency COD requires package.cash-on-demand.item-currency.
• COD is disabled in config.
• Recipient does not have enough money, items, or XP.
• Sender typed an invalid COD amount or item-currency expression.
• Sender typed cancel, off, none, or 0 and expected a price to stay set.
• The package has no valid contents.
• Recipient previews the package but does not click Accept.
• COD preview, accept, or decline is blocked because required COD payment support became unavailable.
• Admin-origin COD payments do not pay the admin because admin COD is a sink cost.
• Server language customization may make button names look different from screenshots.

What Money Mail Is

Money Mail lets players send economy currency through the MailboxGUI inbox system. Instead of handing money directly through a command or trade, the sender chooses a mailbox recipient, enters an amount, and the recipient receives a money delivery item in their inbox.

Money Mail is useful for player payments, shop refunds, gifts, staff rewards, roleplay banking, town systems, and server-run delivery workflows.

Requirements

• money.enabled must be true.
• Vault must be installed.
• A compatible economy plugin must be installed and hooked through Vault.
• MailboxGUI 5.1.1 supports Vault2.0 custom currency names for money mail amount input.
• The sender must have enough money to send the chosen amount.
• The recipient must be a valid MailboxGUI delivery target.
• The server's permissions and mailbox setup must allow the players to access the mail system.

Sending Money

1. Open the mailbox or mail interface.
2. Open Send Mail.
3. Click Send Money.
4. Select the mailbox recipient from the Select Money Recipient GUI.
5. Use filter or type-name tools if they are available on the server.
6. After selecting a recipient, type the amount in chat.
7. Type cancel to cancel the money send flow.

If the amount is valid and the sender has enough money, MailboxGUI withdraws the money and sends it to the recipient's inbox as money mail. There is not a separate confirm screen in this flow after a valid chat amount is entered.

If money mail is disabled or Vault/economy support is unavailable, player and admin money send options are hidden or unavailable.

Choosing a Recipient

Money Mail uses a recipient selector similar to other mail types. The selector lists known mailbox delivery targets, and the selected recipient determines which inbox receives the money mail.

The list can be filtered between recipient groups according to the current filter system. Typed recipient entry can also be used where available in the current plugin flow. Typed names can auto-import players from main-world playerdata when they have joined before. In network mode, typed recipient lookup can also use the shared network index after admins run /mba networkindex on legacy backends.

Entering the Amount

After selecting the recipient, the player types the amount in chat. The value must be greater than 0. Users should normally type a number like 12. MailboxGUI 5.1.1 can also safely parse formatted input such as 12 Coins, 12 Dollars, $12, 12.50, 1,000, or 12 <custom Vault2.0 currency name>.

The amount prompt handles custom currency names, currency symbols, comma-formatted numbers, color codes, hidden formatting, and Vault2.0 renamed currencies. Invalid amounts keep the session active and ask for a valid amount again. If the sender cannot afford the amount, the money is not sent. Typing cancel cancels and returns the player to recipient selection.

Receiving and Claiming Money

Received money mail appears in the inbox as a Money Delivery item. It is stored as a GOLD_NUGGET item with persistent money data, and its lore includes sender information, sent time, amount, and a claim instruction.

Clicking the money mail item in the inbox claims it. Claiming deposits the money into the recipient's economy balance. If the economy deposit succeeds, the recipient gets the received-money message and money claim sound.

Money display formatting is controlled by money.display-format-mode, money.custom-format, and money.amount-format. Modes are PROVIDER for the Vault economy provider format, CUSTOM for the configured custom pattern, and RAW for the formatted number without a currency symbol/name. This affects money mail amounts, admin money mail, COD package prices, and COD return payments. MailboxGUI 5.1.1 can parse Vault2.0 custom currency names and renamed currencies in money mail and Vault-money COD amount prompts, while display output still follows these format settings.

COD Payment Money Mail

COD Packages can create money mail for the sender when package.cash-on-demand.send-reward-in-mail is true. In that case, the sender receives a Cash-On-Demand Payment money mail item.

This is different from normal player-sent money mail, but it is claimed from the inbox the same way. If COD payment-in-mail is disabled, the COD payment is deposited directly instead of delivered as money mail.

Admin Money Mail

Admin tools can send server/admin money deliveries. Admin money can target all mailboxes, online mailbox owners, or a selected recipient depending on permissions.

Admin/server-created money mail uses the configured money.admin-server-name as the sender name. Admin money is useful for event rewards, compensation, server gifts, and staff-issued payments.

The /mba sm command and the API MoneyMailRequest can also create money mail. Command recipients can auto-import joined-before players from main-world playerdata when needed.

/mailbox check can report unchecked money mail when economy support is available.

Troubleshooting Money Mail

• Money Mail is disabled in config.
• Vault is missing.
• The economy plugin is missing or not hooked.
• The sender does not have enough money.
• The amount is invalid or not greater than 0.
• The recipient is not a valid mailbox delivery target.
• The player typed cancel and expected the send to continue.
• Economy deposit failed while claiming.
• Server permissions or region protection prevent normal mailbox access.
• Language customization may make button names look different from screenshots.

What Post Offices Are

Post Office boxes are shared public mailbox access points. Instead of every mailbox access point needing to be a player-owned physical mailbox, server owners can create registered PO Boxes in public areas such as towns, spawn buildings, markets, banks, or mail rooms.

A registered Post Office box opens the normal MailboxGUI menu for the player using it. It is not registered to an individual player, does not create a unique per-player PO Box, does not store a shared PO Box inventory, and does not represent "Player A's PO Box" or "Player B's PO Box."

One public PO Box can be used by many players. Any allowed player can right-click it and see their own personal MailboxGUI menu. Available actions still depend on permissions and enabled features. NPC-based Post Office access is handled separately in the NPC Support section.

Post Office Box Structure

Post Office boxes do not use the fence-post base used by normal physical mailboxes.

A Post Office box is a valid single chest or barrel with a sign attached to the front face of the chest/barrel.

• The container must be a valid single chest or barrel.
• Double chests and trapped chests are still invalid.
• The sign must be attached to the front face of the chest/barrel.
• The admin can select either the container or the attached front sign during registration.
• The plugin must be able to resolve the sign/container pair.
• Post Office boxes do not use the fence-post base.
• Existing chest PO boxes still work, and barrels are supported as an alternate clean container option.
• Decorative blocks can be added around it as long as the container and front sign remain usable.

Creating a Post Office Box

1. Open Admin Tools.
2. Open Post Office Registration.
3. Open Post Office Mailbox Set / Remove.
4. Click Set Post Office Mailbox.
5. Type the Post Office name in chat.
6. Type cancel to cancel the name prompt.
7. After typing a valid name, right-click the valid PO Box container or front sign.
8. Left-click anywhere during selector mode to cancel.

When successful, MailboxGUI registers the PO Box, updates the sign, stores the location, plays the registration sound, and sends a success message.

The Post Office name is for organizing/sign display, not for binding the box to a player. The selected chest/barrel cannot already be a player mailbox.

Sign Format and Numbering

Registered PO Box signs are updated using post-office.mailboxes.sign-format. The current default sign uses the MailboxGUI header, the Post Office name, Public Access, and Right Click.

Current default Post Office sign

line-1: '&6[&lMailbox&r&6]'
line-2: '%postofficename%'
line-3: '&6Public Access'
line-4: '&7Right Click'

Number placeholders remain available for older or custom sign formats: %number%, %po_box_number%, %pobox_number%, %po_box%, and %pobox%. The default sign no longer shows a numbered PO Box.

Player Access

Players right-click a registered Post Office chest/barrel or sign. If allowed, MailboxGUI opens the player's own main mailbox menu through the public PO Box.

• If post-office.mailboxes.allow-any-player-open is true, any player can open a registered PO Box.
• If it is false, players need mailboxgui.player.postoffice.pobox.
• Opening a public Post Office box does not show a shared public inbox.
• Opening a public Post Office box does not open an inbox registered to the Post Office name.
• If post-office.enabled or post-office.mailboxes.enabled is false, PO Box access is disabled.

Registered Mailbox List

Admins can open the Registered Post Office Mailboxes list from the Post Office Mailbox Registration menu. The list shows registered PO Boxes with the Post Office name, world, physical status, and network backend status when network mode is enabled.

Right-clicking an entry unregisters that PO Box if the admin has the removal permission. The list has pagination controls when needed.

• Public PO Boxes are access points, not mailboxes owned by one player.
• Network-aware admin tools show server, world, and status for registered PO Boxes when network mode is enabled.
• Same-backend PO Boxes show Loaded or Unloaded.
• Remote-backend PO Boxes show Remote Server.
• The server line is hidden in single-server mode.
• Network cleanup refreshes signs on backend ownership so GUI lists and signs stay current.

Removing a Post Office Box

Admins can remove PO Boxes through remove selector mode or from the registered mailbox list. In remove selector mode, right-click a registered PO Box container/sign to unregister it. Left-click anywhere during selector mode to cancel.

When removed, MailboxGUI clears the sign if loaded, removes the saved entry, refreshes signs/numbering when configured, and refreshes markers if Dynmap support is active. In network mode, removal broadcasts cleanup so signs and GUI lists refresh on the backend that owns the loaded physical PO Box. Normal players cannot break registered PO Box blocks directly because they are protected.

Protection and Safety

• Registered PO Box containers and signs are protected from normal block breaking.
• Registered PO Box blocks are filtered from block and entity explosions.
• To remove a PO Box properly, admins should unregister it instead of breaking it.
• Post Office boxes cannot be registered on top of already claimed player mailboxes.
• If region protection is installed, admins should make sure players can still right-click PO Boxes.

Troubleshooting Post Offices

• post-office.enabled is false.
• post-office.mailboxes.enabled is false.
• The selected container is not a valid single chest or barrel.
• The sign is not attached to the front face of the chest/barrel.
• The selected box is already registered.
• The selected box is already a claimed player mailbox.
• The player lacks mailboxgui.player.postoffice.pobox when allow-any-player-open is false.
• The player expected a shared inbox; public PO Boxes open that player's own MailboxGUI menu.
• Older screenshots or custom configs may show numbered PO Box signs, while the current default says Public Access / Right Click.
• The world/chunk for a saved PO Box is not loaded, so physical status may show unloaded.
• A region protection plugin blocks right-click interaction.
• Server language customization may make button names look different from screenshots.
• Use the registered mailbox list to verify saved PO Boxes.

What NPC Support Is

NPC Support lets server owners turn Citizens NPCs into public MailboxGUI access points. When a player right-clicks a marked Post Office NPC, MailboxGUI opens the normal mailbox menu for that player.

A Post Office NPC is an access point for the player's own mail. It is not a shared NPC inbox.

NPCs are useful at spawn, cities, markets, banks, town halls, quest hubs, and Post Office buildings. NPC access is separate from physical Post Office boxes, and available mail actions still depend on the server's enabled features and permissions.

Requirements

• Citizens must be installed and enabled.
• MailboxGUI must detect the Citizens API successfully.
• The NPC must be marked as a MailboxGUI Post Office NPC through Admin Tools.
• Players need mailboxgui.player.postoffice.npc to use Post Office NPCs.
• Admins need the proper mailboxgui.admin.tools.postoffice.npc permissions to set or remove NPCs.
• Dynmap is optional and only affects map markers when supported.

Opening NPC Tools

1. Open Admin Tools.
2. Open Post Office Registration.
3. Click NPC Set / Remove.

If Citizens is available, the Admin NPC Tools menu opens. If Citizens is unavailable, the NPC option shows a Citizens missing/unavailable message and clicking it sends the Citizens unavailable message.

The Admin NPC Tools menu contains Set Post Office NPC, Remove Post Office NPC, and Back.

Setting a Post Office NPC

Click Set Post Office NPC to enter NPC add/select mode. Right-click a Citizens NPC to mark it as a Post Office NPC, or left-click anywhere to cancel and return to Admin NPC Tools.

If the NPC is already a Post Office NPC, MailboxGUI sends the already-marked message. On success, MailboxGUI stores persistent NPC data, sends a success message, plays the selector sound, and refreshes Dynmap markers when Dynmap support is active.

Removing a Post Office NPC

Click Remove Post Office NPC to enter NPC remove/select mode. Right-click a marked Citizens Post Office NPC to remove the MailboxGUI marker data, or left-click anywhere to cancel and return to Admin NPC Tools.

If the NPC is not a Post Office NPC, MailboxGUI sends the not-marked message. On success, MailboxGUI removes the marker data, sends a success message, plays the selector sound, and refreshes Dynmap markers when Dynmap support is active.

Player Access

Players right-click a marked Post Office NPC. MailboxGUI checks mailboxgui.player.postoffice.npc. If allowed, the normal MailboxGUI main menu opens, and the player is accessing their own mailbox/mail menu through the NPC.

If the player lacks permission, the no-permission message is sent. If the NPC is not marked as a Post Office NPC, MailboxGUI ignores the NPC for mailbox access.

Dynmap Markers

When Dynmap support is enabled and compatible, Post Office NPCs can appear on the MailboxGUI Dynmap marker layer. Marker data is based on Citizens NPC ID, name, world, and stored location.

Markers refresh after NPCs are marked or unmarked. Dynmap is optional; MailboxGUI does not require Dynmap for NPC access.

If a marked Citizens Post Office NPC is removed, MailboxGUI can refresh NPC markers through the NPC removal cleanup listener when that event is available. MailboxGUI also runs a periodic Citizens registry consistency check to detect Post Office NPC marker changes and refresh Dynmap markers.

NPC Support vs Post Office Boxes

Post Office NPCs and Post Office boxes both provide public access to MailboxGUI. Post Office boxes are physical container/sign structures registered as PO Boxes. Post Office NPCs are Citizens NPCs marked through Admin NPC Tools.

Both open the player's normal mailbox menu when allowed. They are managed through different admin tools and have different setup requirements.

Troubleshooting NPC Support

• Citizens is not installed.
• Citizens is installed but not enabled.
• The Citizens API is unavailable or incompatible.
• The admin lacks mailboxgui.admin.tools.postoffice.npc.set or remove permissions.
• The player lacks mailboxgui.player.postoffice.npc.
• The NPC was never marked as a Post Office NPC.
• The admin right-clicked while not in add/remove selector mode.
• The admin left-clicked and cancelled selector mode.
• The NPC already has the Post Office marker when trying to add.
• The NPC does not have the marker when trying to remove.
• Dynmap markers do not show because Dynmap is missing, disabled, incompatible, or marker display is disabled.
• If a deleted NPC marker looks stale, reload/restart or wait for the periodic Citizens registry consistency check.
• Server language customization may make button names look different from screenshots.

What Admin Tools Are

Admin Tools are MailboxGUI's staff-facing GUI tools for sending server mail, checking player inboxes, managing registered player mailboxes, and opening Post Office management tools.

• Open them with /mailbox admin tools or /mba tools.
• /mailbox admin opens admin help, not the Admin Tools GUI.
• Access depends on the admin permission nodes granted to the staff member.

Opening Admin Tools

Run /mailbox admin tools, or use the admin alias /mba tools. The main Admin Tools menu contains Send Mail, Inbox Check, Post Office Registration, Registered Mailboxes, and Close.

If a staff member lacks the required admin tools permission, MailboxGUI sends the admin no-permission message instead of opening the tool.

Admin Send Mail

Send Mail opens Admin Send Mail. From there, staff choose Letter, Package, or Money. Letter opens a letter type choice for Classic Letter or Book Letter, and each send type opens an audience selector.

The Admin Send Mail GUI is economy-aware. The Money option is hidden when money mail is disabled or Vault/economy support is unavailable, and package slot placement may shift when the money option is hidden.

• All Mailboxes
• Online Mailboxes
• Selected Recipient
• Back

All Mailboxes and Online Mailboxes are bulk targets. Selected Recipient opens the relevant target selector for choosing one or more known mailbox players. Back returns to the previous admin screen.

The admin command shortcuts /mba sl, /mba sla, /mba sp, /mba scod, and /mba sm use the same API-backed send layer for command-driven delivery and can be used by console where supported.

Sending Admin Letters

Admin letters are server-origin letters. The admin chooses Letter, then chooses Classic Letter or Book Letter. For Classic Letter, the admin chooses an audience and types the message in chat. For selected recipients, the admin selects target(s), then types the message in chat.

Typing cancel cancels the prompt and returns to the previous screen. Admin letters use the configured letter.admin-server-name as the sender name.

For Book Letter, the admin chooses All Mailboxes, Online Mailboxes, or Selected Recipient, receives a temporary Book and Quill, manually right-clicks it, writes pages, clicks Sign, enters a title, and clicks Sign and Close. Admin Book Letters never include Reply links. Cancel restores the original hotbar item and returns to the admin letter type selection/admin send flow.

Sending Admin Packages

Admin packages are server-origin package deliveries. The admin chooses Package, then an audience. For selected recipients, the target selector opens first. Package compose opens after the audience or recipient is selected.

• The admin places items into the package slots.
• The package cannot be empty.
• Package nesting is blocked.
• Non-empty shulker boxes are blocked when the loaded shulker protection setting is enabled.
• Admin package experience can be used when package experience is enabled and the admin has permission.
• Admin package COD can be used when at least one COD payment option is available.
• Admin COD package compose blocks, hides, or disables COD setup when COD support is unavailable.
• Admin-origin COD packages act as sink costs and do not pay an admin/server sender unless a real return recipient is configured.
• Admin packages use package.admin-server-name as the sender name.
• Admin command packages can use saved item templates through template:<id>:amount or t:<id>:amount.

Sending Admin Money

Admin money mail creates server-origin money deliveries. Money mail requires money.enabled and Vault/economy support.

The admin chooses Money, selects an audience, then types an amount in chat. Typed amounts must be valid and greater than 0. Admin money mail uses money.admin-server-name as the sender name.

/mba sm shows a clear unavailable message when money is disabled or no active Vault economy provider exists. /mba scod shows a clear unavailable message when COD is disabled or no COD payment option is available.

Bulk Audience Behavior

• All Mailboxes sends to available mailbox delivery targets.
• Online Mailboxes sends to online players.
• Selected Recipient lets the admin choose target(s) from a selector.
• admin-mail.include-sender-in-bulk-audiences controls whether the admin sender can be included in All Mailboxes and Online Mailboxes.
• Bulk mail only sends to targets that can accept the created mail item.

Inbox Check

Inbox Check opens a player target selector. The selector supports filter cycling and typed player name entry; it starts with the Online filter by default and can cycle Online, All, and Offline. In network mode, recipient and target refresh behavior can use shared MailboxGUI player data and network presence so admins can find players known to other backends.

Admins with mailboxgui.admin.tools.inboxcheck.see can inspect a player inbox. Admins with mailboxgui.admin.tools.inboxcheck.edit can make changes. In edit mode, right-clicking classic letters or money mail removes them. Book Letter items show Left-Click to Read and Right-Click to Delete; they do not show Shift-Left-Click to Take in admin inbox check. When an admin reads a player Book Letter, Reply is hidden and the book shows Back to Player Inbox.

Package items in admin inbox check now show Right-Click to Manage this package. This applies to normal packages, pending COD packages, accepted COD packages, returned COD packages, and item-currency COD payment packages. Right-clicking a package opens Admin Package Action. The target inbox is saved when edits are made, and paper notification refreshes are requested after inbox/admin changes. In network mode, inbox/admin edits can publish refresh events so other backends reconcile inbox state and paper notifications.

Admin Package Action

When editing a player inbox, clicking a package opens the Admin Package Action GUI. This is an admin inbox editing tool, not the normal player package receive flow.

• Take Package Contents gives the package contents to the admin and removes the package from the target inbox.
• Delete Package removes the package from the target inbox.
• Cancel returns to the player inbox view.

Clear Player Inbox

Admin Inbox View includes a clear inbox option for editors. Clicking it opens a confirmation GUI. Confirming clears the target player's inbox, while declining returns without clearing.

Registered Mailboxes

Registered Mailboxes lets admins inspect and manage saved player mailbox registrations. The target selector can show players with registered mailboxes or all known players depending on the filter. Selecting a player opens that player's registered mailbox detail list. In network mode, mailbox entries show server, world, and status.

• Admins can add/register a mailbox for that player through the admin registration prompt.
• Admins can right-click a listed mailbox to open the unregister confirmation flow.
• Same-backend mailboxes show Loaded or Unloaded.
• Remote-backend mailboxes show Remote Server.
• The server line is hidden in single-server mode.
• Confirming removal unregisters that saved mailbox, clears the sign if loaded, and refreshes paper notifications and GUI lists.
• In network mode, removal broadcasts cleanup so signs, paper notifications, and GUI lists refresh across backends.
• Existing old single-server data can be adopted by the current backend when network mode is enabled if the physical mailbox is loaded.

Related Admin Commands

• /mailbox admin shows admin help.
• /mailbox admin tools opens the Admin Tools GUI.
• /mba tools is the admin alias flow for opening Admin Tools.
• /mailbox admin reload reloads MailboxGUI config/language synchronization.
• When network.enabled=true, /mba reload reloads the local backend and broadcasts a network reload request.
• /mailbox admin import player <name...> imports player data into MailboxGUI data.
• /mailbox admin updatecheck or /mba updatecheck manually checks the website release system and displays the official download link.
• /mailbox admin update or /mba update starts the update flow, and /mailbox admin update confirm or /mba update confirm downloads and stages the new jar for this backend's next restart. In Velocity-style or BungeeCord-style network setups, run the update command on each backend server that has MailboxGUI installed, then restart each backend.
• /mailbox admin convert <YAML|SQLITE|MYSQL> or /mba convert <YAML|SQLITE|MYSQL> converts from the active backend to the selected backend while network mode is disabled.
• /mailbox admin convert current or /mba convert current shows the current active/configured storage mode.
• /mailbox admin networkindex or /mba networkindex indexes local backend playerdata into shared network player data when network mode is enabled.
• /mailbox admin clean or /mba clean starts generated backup cleanup confirmation.
• /mba sl, /mba sla, /mba sp, /mba scod, and /mba sm are admin/API-backed command send flows.
• /mba itemtemplate and /mba it manage item templates for command package item specs.
• Console can use supported admin reload/convert command flows where the source permits it.

Admin command send resolves recipients before sending. If any requested command recipient cannot be resolved/imported, the whole send fails instead of sending partial mail.

Troubleshooting Admin Tools

• Staff member lacks mailboxgui.admin or the specific admin tool permission.
• /mailbox admin was used instead of /mailbox admin tools.
• Money mail is unavailable because Vault/economy is missing.
• Package COD is unavailable because COD is disabled or no COD payment option is available.
• Admin money send is hidden/blocked because the economy provider is unavailable.
• Admin command COD is hidden/blocked when the requested COD payment type is unavailable.
• No valid targets exist for the selected audience.
• A selected player is not known to MailboxGUI.
• A command send recipient could not be resolved/imported, so no partial send was performed.
• Admin typed cancel during a chat prompt.
• Admin package is empty.
• Package contains a nested MailboxGUI package.
• Package contains a blocked non-empty shulker box.
• Inbox editing requires edit permission, not just see permission.
• Server language customization may make button names look different from screenshots.

What Storage Controls

Storage controls where MailboxGUI saves persistent plugin data, including player mailbox data, inbox mail data, delayed mail queue data, and Post Office mailbox data. MailboxGUI supports YAML, SQLite, and MySQL so servers can choose the storage backend that fits their size and maintenance style. Network mode requires shared MySQL/MariaDB storage; Redis is only used for network coordination, not as the mail data store.

The delayed mail queue is persistent and supports delayed letter, package, and money delivery through config, commands, and API calls. Delayed mail data is handled through the active storage provider, and standalone YAML delayed mail can import when needed.

Storage Config Example

Example storage config

storage:
  # Valid types: YAML, SQLITE, MYSQL
  # Fresh installs default to SQLITE.
  # Legacy YAML upgrades may stay on YAML automatically for safety.
  type: SQLITE

  sqlite:
    # Path is relative to plugins/MailboxGUI/
    file: data/data.db

  mysql:
    host: localhost
    port: 3306
    database: mailboxgui
    username: root
    password: ''
    use-ssl: false

• storage.type controls the active backend.
• SQLITE uses a local database file.
• YAML uses the data/playerdata and data/postofficedata folders.
• MYSQL uses the configured database connection.
• Changing storage.type alone does not copy existing data. Use the conversion command for that.
• Use /mba convert MYSQL before enabling network mode.

Available Storage Types

• YAML: flat YAML files under plugins/MailboxGUI/data/playerdata and plugins/MailboxGUI/data/postofficedata.
• SQLITE: local SQLite database file under plugins/MailboxGUI/data/data.db.
• MYSQL: MySQL database storage using the configured database connection.

Fresh installs default to SQLITE. Legacy YAML upgrades can remain on YAML automatically for safety. MySQL is useful for servers that specifically want database-backed storage and have a reliable MySQL or compatible MariaDB server. Network mode requires MYSQL on every backend.

SQLite Startup Example

This is an example of the kind of startup information a server owner may see. The exact wording can vary by MailboxGUI version and configuration.

Example SQLite startup console output

[MailboxGUI] Storage Backend: SQLITE
[MailboxGUI] SQLite database file: plugins/MailboxGUI/data/data.db
[MailboxGUI] Player data path: plugins/MailboxGUI/data/playerdata
[MailboxGUI] Post Office data path: plugins/MailboxGUI/data/postofficedata
[MailboxGUI] MailboxGUI storage provider initialized successfully.

Fresh Installs and Legacy Upgrades

• New installs use SQLITE by default.
• Upgrades from older YAML-based MailboxGUI versions may be kept on YAML when legacy data is detected.
• Legacy player data from plugins/MailboxGUI/mailboxdata is copied into plugins/MailboxGUI/data/playerdata.
• Legacy Post Office data from plugins/MailboxGUI/postofficedata/mailboxes.yml is copied into plugins/MailboxGUI/data/postofficedata/mailboxes.yml.
• Legacy copy migration does not overwrite existing new-layout files.
• This helps prevent old data from being ignored by a fresh SQLite default.

YAML Storage Folder Structure

YAML storage folder structure

plugins/
└── MailboxGUI/
    └── data/
        ├── playerdata/
        │   ├── 00000000-0000-0000-0000-000000000000.yml
        │   ├── 11111111-1111-1111-1111-111111111111.yml
        │   └── ...
        └── postofficedata/
            └── mailboxes.yml

• playerdata contains per-player YAML files named by UUID.
• postofficedata/mailboxes.yml stores Post Office mailbox data.
• Manual edits should only be done while the server is stopped.

SQLite Storage Layout

• SQLite file path defaults to plugins/MailboxGUI/data/data.db.
• SQLite is the default for fresh installs.
• SQLite keeps plugin data in a local database file instead of many individual YAML files.
• SQLite is a good default for most single-server setups.
• Server owners should back up data/data.db before major upgrades or conversions.

SQLite database path

plugins/MailboxGUI/data/data.db

MySQL Configuration Example

Example MySQL storage config

storage:
  type: MYSQL

  mysql:
    host: 127.0.0.1
    port: 3306
    database: mailboxgui
    username: mailboxgui_user
    password: 'change-this-password'
    use-ssl: false

• The database and user should exist before switching to MYSQL.
• MailboxGUI validates the connection and creates or validates tables.
• Required tables are mailboxgui_playerdata and mailboxgui_postoffice.
• The Post Office data row uses the internal id mailboxes.
• If MySQL validation fails on startup, MailboxGUI falls back to SQLITE.
• Network mode requires all backends to use the same shared MySQL/MariaDB database.

Confirm active storage before enabling network mode

/mba convert current

Active storage: MYSQL
Configured storage: MYSQL

Changing Storage Type Safely

• Do not simply change storage.type on a live server and expect data to move automatically.
• Use the storage conversion command to move data between storage backends.
• Stop and back up the server before production storage changes when possible.
• Confirm the current active storage type first with /mailbox admin convert current or /mba convert current.
• Convert from the active type to the target type.
• Convert to MYSQL before enabling network mode.
• When network.enabled=true, conversion is disabled/refused and YAML/SQLite are not allowed.
• Verify data after conversion before deleting old backups or old data.
• Generated backups can be reviewed and cleaned later with /mailbox admin clean or /mba clean.

Storage Conversion Command

Storage conversion command

/mailbox admin convert current
/mba convert current

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

Examples:

/mailbox admin convert SQLITE
/mailbox admin convert MYSQL
/mba convert YAML

• current shows the active storage backend.
• Target conversion converts from the active backend to the selected backend.
• Same-target conversion is refused.
• Conversion requires mailboxgui.admin.convert or mailboxgui.admin.
• Conversion to MYSQL validates MySQL before changing config.
• Convert before enabling network mode. Storage conversion is hidden/refused when network.enabled=true.
• Backups are created before overwriting target storage.
• Storage conversion backups are stored under plugins/MailboxGUI/data/backups/storage-conversions/.

Storage Conversion Success Example

This example shows the conversion flow admins should expect conceptually. It is not a guaranteed exact console copy for every version.

Example successful conversion output

[MailboxGUI] Starting storage conversion: YAML -> SQLITE
[MailboxGUI] Saving loaded mailbox and Post Office data before conversion...
[MailboxGUI] Backup created: plugins/MailboxGUI/data/backups/storage-conversions/20260510-184522-YAML-to-SQLITE
[MailboxGUI] Copied player data entries: 42
[MailboxGUI] Copied Post Office data: yes
[MailboxGUI] Updated config.yml storage.type to SQLITE
[MailboxGUI] Reloaded storage provider and mailbox data.
[MailboxGUI] Storage conversion completed successfully.

Conversion Backup Folder Structure

Conversion backup folder structure

plugins/
└── MailboxGUI/
    └── data/
        └── backups/
            └── storage-conversions/
                └── 20260510-184522-YAML-to-SQLITE/
                    ├── config.yml
                    ├── source/
                    │   ├── playerdata/
                    │   └── postofficedata/
                    └── target-before-clear/
                        └── ...

• The timestamp and conversion direction are included in the folder name.
• The backup includes config.yml.
• The backup includes a source provider snapshot.
• If target data already existed, the target snapshot is backed up before it is cleared.
• This backup is important because conversion clears the target before copying data.

MySQL Validation and Fallback

• MYSQL startup validates connection and table creation.
• If validation fails, MailboxGUI logs severe/red console messages.
• The plugin changes storage.type back to SQLITE and starts on SQLite instead of failing the whole plugin startup.
• Conversion to MYSQL also validates first.
• If MySQL validation fails during conversion, config.yml is not changed and data is not copied to the failed target.

This is an example fallback log to show the behavior. Exact wording may vary by version and configuration.

Example MySQL fallback console output

[MailboxGUI ERROR] Failed to connect to MYSQL storage.
[MailboxGUI ERROR] MySQL validation failed during startup.
[MailboxGUI ERROR] Falling back to SQLITE so MailboxGUI can continue loading.
[MailboxGUI] Updated config.yml storage.type to SQLITE.
[MailboxGUI] Storage Backend: SQLITE
[MailboxGUI] SQLite database file: plugins/MailboxGUI/data/data.db

Backup Cleanup

MailboxGUI-generated backups are consolidated under plugins/MailboxGUI/data/backups/. Categories include pre-3.0.0-upgrade, pre-4.0.0-storage-upgrade, yaml-sync, language, storage-conversions, and newer MailboxGUI-generated backup folders created by recent upgrade/sync flows.

Backup cleanup command

/mailbox admin clean
/mba clean

• Requires mailboxgui.admin.clean or mailboxgui.admin.
• Cleans generated MailboxGUI backup files from old upgrades, syncs, conversions, and newer backup folders under plugins/MailboxGUI/data/backups/ after confirmation.
• Active mail data and active config files are not touched.
• Internal upgrade marker files are preserved where applicable.
• Use cleanup only after confirming mail data, config, language files, and storage are working correctly.

Recommended Storage Choices

• Use SQLITE for most fresh single-server installs.
• Use YAML when upgrading older YAML installs and you want the simplest compatibility path.
• Use MYSQL when you have a maintained MySQL/MariaDB server and want database-backed storage.
• Use MYSQL for every backend when network mode is enabled.
• Redis is only needed for network mode.
• Always test conversions on a backup before relying on them for a production server.

Troubleshooting Storage

• storage.type is misspelled or invalid, causing fallback to SQLITE.
• MySQL host, port, database, username, password, or SSL setting is wrong.
• MySQL database/user does not exist or lacks permissions.
• MySQL conversion fails validation, so config is not changed.
• Network mode is enabled before conversion to MySQL, so the convert command is refused.
• The wrong source type was used in the conversion command.
• Source and target types are the same.
• Source storage has no readable player or Post Office data.
• Server was not stopped/backed up before manual file edits.
• YAML files were edited while the server was running.
• Data appears missing because the server is pointed at a different storage backend than the one containing the data.
• Old generated backups can be cleaned with /mailbox admin clean after verifying active data.

Complete Default config.yml

This example shows the current default MailboxGUI config.yml values without comments. Server owners can use it as a quick reference, but should still edit their own generated config.yml instead of blindly replacing it.

Complete default config.yml

config-version: 12

storage:
  type: SQLITE

  sqlite:
    file: data/data.db

  mysql:
    host: localhost
    port: 3306
    database: mailboxgui
    username: root
    password: ''
    use-ssl: false

mailbox:
  max-mailboxes-per-player: 3

  allow-player-self-send: true

  new-mail-notification:
    enabled: true
    item: PAPER
    vertical-offset: 1.35
    refresh-interval-seconds: 60

  detection:
    refresh-signs-on-load: true

  sign-format:
    line-1: '&6[&lMailbox&r&6]'
    line-2: '%player%'
    line-3: '&bPersonal Mail'
    line-4: '&7Right Click'

admin-mail:
  include-sender-in-bulk-audiences: true

post-office:
  enabled: true

  mailboxes:
    enabled: true

    allow-any-player-open: true

    renumber-after-remove: true

    refresh-signs-on-load: true

    sign-format:
      line-1: '&6[&lMailbox&r&6]'
      line-2: '%postofficename%'
      line-3: '&6Public Access'
      line-4: '&7Right Click'

dynmap:
  enabled: true

  marker-set:
    id: 'mailboxgui-mailboxes'

    label: 'Mailboxes/PO Boxes/NPC'

    hide-by-default: false

    layer-priority: 10

  markers:
    player-mailboxes:
      enabled: true

      icon-id: 'chest'

      label-format: '%player% Mailbox #%number%'

      description:
        - '<b>MailboxGUI Player Mailbox</b>'
        - 'Player: %player%'
        - 'Mailbox: #%number%'
        - 'World: %world%'
        - 'Status: %status%'

    post-office-mailboxes:
      enabled: true

      icon-id: 'chest'

      label-format: '%postofficename% PO Box #%number%'

      description:
        - '<b>MailboxGUI Post Office Box</b>'
        - 'Post Office: %postofficename%'
        - 'PO Box: #%number%'
        - 'World: %world%'
        - 'Status: %status%'

    post-office-npcs:
      enabled: true

      icon-id: 'walk'

      label-format: 'Post Office NPC: %npc%'

      description:
        - '<b>MailboxGUI Post Office NPC</b>'
        - 'NPC: %npc%'
        - 'NPC ID: %id%'
        - 'World: %world%'

  update:
    refresh-on-startup: true

    refresh-on-reload: true

    refresh-on-register: true

    refresh-on-unregister: true

locale:
  default: en

  auto-detect-player-locale: true

letter:
  enabled: true

  delivery-delay-seconds: 0

  admin-server-name: '&a&lServer'

package:
  enabled: true

  deny-loaded-shulker-box: true

  size-in-rows: 3

  delivery-delay-seconds: 0

  admin-server-name: '&a&lServer'

  experience:
    enabled: true

    max-experience-per-package: -1

    withdraw-from-sender-on-send: true

    item:
      material: EXPERIENCE_BOTTLE

      display-name: '&aExperience Package'

      lore:
        - '&7Stored Experience: &a%experience%'
        - '&e&lAny click to claim'

      cod-preview-lore:
        - '&7Stored Experience: &a%experience%'
        - '&cAccept COD Package before you can claim this XP'

  cash-on-demand:
    enabled: true

    vault-economy-currency: true

    item-currency: true

    send-reward-in-mail: true

  lore:
    standard-package:
      - '&7From: &f%sender%'
      - '&7Right-click to open'

    cash-on-demand-package:
      - '&7From: &f%sender%'
      - '&7Right-click to preview contents'

money:
  enabled: true

  display-format-mode: PROVIDER

  custom-format: "$%amount%"

  amount-format: "#,##0.00"

  admin-server-name: '&a&lServer'

update-checker:
  enabled: true

  channel: release

  check-on-startup: true

  notify-admins-on-join: true

  notify-permission: "mailboxgui.admin"

config-version

config-version

config-version: 12

• Default: 12
• Internal config schema/version value used by MailboxGUI's config synchronizer.
• Server owners normally should not manually change this unless instructed during support.
• This is not the plugin version.

Storage Type

Storage Type

storage:
  type: SQLITE

• Default: SQLITE
• Valid values: YAML, SQLITE, MYSQL.
• Controls the active storage backend.
• Fresh installs default to SQLITE.
• Single-server setups can use SQLITE, YAML, or MYSQL.
• Network mode requires MYSQL/MySQL-compatible MariaDB storage on every backend.
• Missing or invalid values fall back to SQLITE.
• Legacy YAML installs can be kept on YAML automatically for upgrade safety.
• Changing this value alone does not move data. Use the storage conversion command to migrate existing data.

SQLite Storage File

SQLite Storage File

storage:
  sqlite:
    file: data/data.db

• Default: data/data.db
• Path is relative to plugins/MailboxGUI/.
• The default full plugin-relative path is plugins/MailboxGUI/data/data.db.
• Used only when storage.type is SQLITE.

MySQL Connection

MySQL Connection

storage:
  mysql:
    host: localhost
    port: 3306
    database: mailboxgui
    username: root
    password: ''
    use-ssl: false

• Used only when storage.type is MYSQL.
• The database and user should exist before switching to MYSQL.
• MariaDB can be used when it is MySQL-compatible for your JDBC/server environment.
• MailboxGUI validates MySQL before startup/conversion use.
• If startup validation fails, MailboxGUI falls back to SQLITE.
• Network mode requires every backend to use the same shared MySQL/MariaDB database.

Max Mailboxes Per Player

Max Mailboxes Per Player

mailbox:
  max-mailboxes-per-player: 3

• Default: 3
• Controls how many physical player mailboxes a player can register.
• Higher values allow multiple personal mailbox locations per player.
• Lower values restrict physical mailbox registrations.
• This does not control public Post Office boxes.

Allow Player Self Send

Allow Player Self Send

mailbox:
  allow-player-self-send: true

• Default: true
• Possible values: true or false.
• true: players can select themselves as recipients in normal sending flows.
• false: players are hidden/blocked from sending mail to themselves.
• Applies to normal player recipient menus where self-send filtering is supported.

New Mail Notification

New Mail Notification

mailbox:
  new-mail-notification:
    enabled: true
    item: PAPER
    vertical-offset: 1.35
    refresh-interval-seconds: 60

• The indicator is owner-visible.
• It clears when the mailbox owner opens their inbox.
• This applies to registered physical player mailboxes, not general wiki UI.

Mailbox Detection

Mailbox Detection

mailbox:
  detection:
    refresh-signs-on-load: true

• Default: true
• Possible values: true or false.
• true: MailboxGUI refreshes saved player mailbox signs during startup/reload when the blocks are loaded.
• false: saved signs are not automatically refreshed on load.

Player Mailbox Sign Format

Player Mailbox Sign Format

mailbox:
  sign-format:
    line-1: '&6[&lMailbox&r&6]'
    line-2: '%player%'
    line-3: '&bPersonal Mail'
    line-4: '&7Right Click'

• Controls the four lines written to registered physical player mailbox signs.
• Supports color codes using &.
• Supports placeholders: %player%, %number%, %mailbox_number%, and %mailboxnumber%.
• The current default sign no longer displays a mailbox number, but number placeholders still work for older or custom formats.

Player Notification Preferences

Player Notification Preferences

Player-controlled commands:
/mailbox settings notification offline <simple|advanced|off>
/mailbox settings notification online <on|off>
/mailbox settings notification soundalert <on|off>

• MailboxGUI 5.1.1 player notification defaults are not configured in config.yml.
• Players control offline summary mode, online chat alerts, and online sound alerts with /mailbox settings.
• Server sound definitions are managed through sounds.yml.

Admin Bulk Sender Inclusion

Admin Bulk Sender Inclusion

admin-mail:
  include-sender-in-bulk-audiences: true

• Default: true
• Possible values: true or false.
• true: admin bulk audiences may include the admin sender.
• false: admin bulk audiences exclude the admin sender.
• Applies to admin All Mailboxes and Online Mailboxes audience flows.

Post Office Enabled

Post Office Enabled

post-office:
  enabled: true

• Default: true
• Possible values: true or false.
• Enables/disables Post Office systems.
• When false, Post Office mailbox opening and Post Office registration tools are disabled.

Post Office Mailboxes

Post Office Mailboxes

post-office:
  mailboxes:
    enabled: true
    allow-any-player-open: true
    renumber-after-remove: true
    refresh-signs-on-load: true

Post Office Sign Format

Post Office Sign Format

post-office:
  mailboxes:
    sign-format:
      line-1: '&6[&lMailbox&r&6]'
      line-2: '%postofficename%'
      line-3: '&6Public Access'
      line-4: '&7Right Click'

• Controls the four sign lines for registered Post Office boxes.
• Supports color codes using &.
• Supports placeholders: %postofficename%, %number%, %po_box_number%, %pobox_number%, %po_box%, and %pobox%.
• The current default sign no longer displays a numbered PO Box, but number placeholders still work for older or custom formats.

Dynmap Enabled

Dynmap Enabled

dynmap:
  enabled: true

• Default: true
• Possible values: true or false.
• Enables/disables MailboxGUI Dynmap integration globally.
• Dynmap is optional. MailboxGUI works without Dynmap.
• Dynmap markers only work when Dynmap is installed, enabled, and compatible with the server version.

Dynmap Marker Set

Dynmap Marker Set

dynmap:
  marker-set:
    id: 'mailboxgui-mailboxes'
    label: 'Mailboxes/PO Boxes/NPC'
    hide-by-default: false
    layer-priority: 10

Dynmap Player Mailbox Markers

Dynmap Player Mailbox Markers

dynmap:
  markers:
    player-mailboxes:
      enabled: true
      icon-id: 'chest'
      label-format: '%player% Mailbox #%number%'
      description:
        - '<b>MailboxGUI Player Mailbox</b>'
        - 'Player: %player%'
        - 'Mailbox: #%number%'
        - 'World: %world%'
        - 'Status: %status%'

• Supported placeholders: %player%, %number%, %world%, %status%.

Dynmap Post Office Box Markers

Dynmap Post Office Box Markers

dynmap:
  markers:
    post-office-mailboxes:
      enabled: true
      icon-id: 'chest'
      label-format: '%postofficename% PO Box #%number%'
      description:
        - '<b>MailboxGUI Post Office Box</b>'
        - 'Post Office: %postofficename%'
        - 'PO Box: #%number%'
        - 'World: %world%'
        - 'Status: %status%'

• Supported placeholders: %postofficename%, %number%, %world%, %status%.

Dynmap Post Office NPC Markers

Dynmap Post Office NPC Markers

dynmap:
  markers:
    post-office-npcs:
      enabled: true
      icon-id: 'walk'
      label-format: 'Post Office NPC: %npc%'
      description:
        - '<b>MailboxGUI Post Office NPC</b>'
        - 'NPC: %npc%'
        - 'NPC ID: %id%'
        - 'World: %world%'

• Supported placeholders: %npc%, %id%, %world%.
• Dynmap marker support depends on Dynmap having a compatible release build for the server version.
• Dynmap markers are not supported on 26.1.x or 26.2.x. Core MailboxGUI features still work without Dynmap markers.
• MailboxGUI continues to run normally without Dynmap markers.

Dynmap Marker Refresh

Dynmap Marker Refresh

dynmap:
  update:
    refresh-on-startup: true
    refresh-on-reload: true
    refresh-on-register: true
    refresh-on-unregister: true

Locale Configuration

Locale Configuration

locale:
  default: en
  auto-detect-player-locale: true

Letter Configuration

Letter Configuration

letter:
  enabled: true
  delivery-delay-seconds: 0
  admin-server-name: '&a&lServer'

Package Core Configuration

Package Core Configuration

package:
  enabled: true
  deny-loaded-shulker-box: true
  size-in-rows: 3
  delivery-delay-seconds: 0
  admin-server-name: '&a&lServer'

Package Experience Configuration

Package Experience Configuration

package:
  experience:
    enabled: true
    max-experience-per-package: -1
    withdraw-from-sender-on-send: true

Package Experience Item

Package Experience Item

package:
  experience:
    item:
      material: EXPERIENCE_BOTTLE
      display-name: '&aExperience Package'
      lore:
        - '&7Stored Experience: &a%experience%'
        - '&e&lAny click to claim'
      cod-preview-lore:
        - '&7Stored Experience: &a%experience%'
        - '&cAccept COD Package before you can claim this XP'

Cash-On-Demand Configuration

Cash-On-Demand Configuration

package:
  cash-on-demand:
    enabled: true
    vault-economy-currency: true
    item-currency: true
    send-reward-in-mail: true

Package Lore Configuration

Package Lore Configuration

package:
  lore:
    standard-package:
      - '&7From: &f%sender%'
      - '&7Right-click to open'
    cash-on-demand-package:
      - '&7From: &f%sender%'
      - '&7Right-click to preview contents'

• Color codes use &.

Money Mail Configuration

Money Mail Configuration

money:
  enabled: true
  display-format-mode: PROVIDER
  custom-format: "$%amount%"
  amount-format: "#,##0.00"
  admin-server-name: '&a&lServer'

Money Display Format Mode

Money Display Format Mode

money:
  display-format-mode: PROVIDER

• Default: PROVIDER
• PROVIDER: use the Vault economy provider format(amount) output.
• CUSTOM: render using money.custom-format after formatting the numeric amount.
• RAW: show the formatted number without currency symbol or currency name.
• This affects money mail amounts, admin money mail, COD package prices, and COD return/payment displays.

Money Custom Format

Money Custom Format

money:
  custom-format: "$%amount%"

• Default: $%amount%
• Used when money.display-format-mode is CUSTOM.
• %amount% is replaced with the value formatted by money.amount-format.

Money Amount Format

Money Amount Format

money:
  amount-format: "#,##0.00"

• Default: #,##0.00
• Controls decimal grouping and precision before CUSTOM or RAW output is rendered.
• PROVIDER mode relies on the economy provider display format instead.

Update Checker Configuration

Update Checker Configuration

update-checker:
  enabled: true
  channel: release
  check-on-startup: true
  notify-admins-on-join: true
  notify-permission: "mailboxgui.admin"

• Manual update checks can be run with /mailbox admin updatecheck or /mba updatecheck.
• Version checks use the website release system.
• Update URLs are built into the plugin and are not exposed in config.yml.
• Update messages display the official download page: https://plugins.imagine-craft.net/mailboxgui/download/

Sound Alerts

Sound Alerts

sounds-config-version: 3

sounds:
  online-mail-alert:
    sound: BLOCK_NOTE_BLOCK_PLING
    volume: 1.0
    pitch: 1.4

• MailboxGUI 5.1.1 includes online-mail-alert in sounds.yml.
• The current sounds.yml file uses sounds-config-version: 3.
• Players can control the online sound alert with /mailbox settings notification soundalert <on|off>.
• Player notification preferences are not configured in config.yml.

Language Upgrade System

Language Upgrade System

language/messages_*.yml file-version: 14

• Current MailboxGUI 5.1.1 language/message files use file-version: 14.
• MailboxGUI preserves customized language text where possible.
• This release updates messages_zh_cn.yml, adds messages_zh_hk.yml, and keeps messages_zh_tw.yml available.
• The language upgrade system can update old default zh_cn text to the new contributed translation while preserving server-owner custom edits.
• Special thanks to nice for contributing the updated zh_cn and new zh_hk language files.

What Network Mode Is

Network mode was introduced in MailboxGUI 5.0.0 and remains optional in 5.1.0 for multiple backend servers sharing MailboxGUI data. It is useful for Velocity-style or BungeeCord-style networks such as Live + Legacy. Every backend that uses MailboxGUI runs MailboxGUI.

• Shared mail data lives in MySQL/MariaDB.
• Redis is used for network messages, presence, refreshes, locks, and cross-server coordination.
• Single-server servers should leave network.enabled false.

When You Need Network Mode

• Use it when two or more backend servers need to share MailboxGUI mail data.
• Use it for Velocity-style or BungeeCord-style networks where players move between backends and still need the same mail identity.
• Do not enable it for a normal standalone Spigot, Paper, or Purpur server.

Requirements

• MySQL/MariaDB shared storage.
• Redis reachable by every backend.
• Unique server-id per backend.
• Same MailboxGUI version on every backend.
• Same database on every backend.
• Same Redis instance on every backend.

Safe Setup Order

1. Back up plugin data.
2. Keep network.enabled false.
3. Configure MySQL in main config.yml.
4. Start one backend only.
5. Run /mba convert MYSQL.
6. Confirm /mba convert current shows MYSQL.
7. Stop backend.
8. Configure plugins/MailboxGUI/network/config.yml on every backend.
9. Give each backend a unique server-id and server-display-name.
10. Start one backend and check startup.
11. Start remaining backends.
12. Test mail delivery, recipient lookup, admin tools, and paper notifications.

MySQL/MariaDB Storage

Network mode requires all backends to use storage.type: MYSQL against the same shared MySQL/MariaDB database. YAML and SQLite are not allowed in network mode.

MySQL storage reminder

storage:
  type: MYSQL
  mysql:
    host: 172.18.0.1
    port: 3306
    database: mailboxgui
    username: mailboxgui
    password: 'change-this'

Redis Configuration

Redis must be reachable by every backend and should be the same Redis instance on every backend. In Docker/Pterodactyl setups, 127.0.0.1 usually means inside the Minecraft container, not the Ubuntu host.

Redis example

redis:
  host: 172.18.0.1
  port: 6379
  password: 'change-this'
  database: 0
  use-ssl: false

Example network/config.yml

network:
  enabled: true
  server-id: live
  server-display-name: 'Live'
  require-shared-storage: true

mysql:
  require-active-storage-type: MYSQL

redis:
  host: 172.18.0.1
  port: 6379
  password: 'change-this'
  database: 0
  use-ssl: false

Startup/validation example

[MailboxGUI] Network mode enabled for server-id live (Live).
[MailboxGUI] Active storage: MYSQL.
[MailboxGUI] Shared storage requirement satisfied.
[MailboxGUI] Redis connection established.
[MailboxGUI] Network coordination ready.

Additional Network Keys

The bundled network/config.yml also includes these source-backed sections. Keep examples short in the wiki and use the generated file on your server for the full comments.

• There is no redis.enabled setting.
• Redis settings are ignored when network.enabled is false.
• Redis is required and validated when network.enabled is true.
• MailboxGUI runs on backend servers that use mail; it does not need to run on the proxy itself.

Backend server-id examples

Live

network:
  enabled: true
  server-id: live
  server-display-name: 'Live'

Legacy

network:
  enabled: true
  server-id: legacy
  server-display-name: 'Legacy'

Storage Conversion Rules

• Convert before enabling network mode.
• All backends must use MySQL/MariaDB in network mode.
• YAML and SQLite are not allowed in network mode.

Convert Command Disabled in Network Mode

The convert command is disabled/refused when network.enabled=true. Use /mba convert MYSQL before enabling network mode, then verify with /mba convert current.

Network-Wide Recipient Lookup

Typed recipient lookup for player-sent mail and admin-sent mail is network-aware when network mode is enabled. It can use shared MailboxGUI data and the shared network player index.

• If a player joined a backend before MailboxGUI network mode was installed, they may not be known to shared MailboxGUI data yet.
• Run /mba networkindex on the backend where that player has playerdata before expecting players or admins to find that name through typed recipient lookup.
• This helps players send mail to older/legacy players who have not logged in since MailboxGUI was installed.

Network Player Index and Importing Legacy Players

In network mode, MailboxGUI can look up recipients from shared MailboxGUI player data and the shared network player index. /mba networkindex scans the current backend server's local playerdata and stores known player UUID/name information in that shared index.

• Run /mba networkindex on each backend that has old/local players you want available for network-wide recipient lookup.
• This is especially important for Legacy/old-world servers where players joined before MailboxGUI 5.0.0 network mode was installed.
• Before using /mailbox admin import player <name> on a network setup, run /mba networkindex on the relevant backends.
• /mba networkindex lets the import command find players known on other backends.
• Without indexing, /mailbox admin import may only find players already present in shared MailboxGUI data or local playerdata.
• After indexing, an admin can import players into MailboxGUI data from the shared network player index.

Legacy import example

OldPlayer123 only played on the Legacy backend.
Live does not know OldPlayer123 yet.

Run this on Legacy:
/mba networkindex

Now Live can find OldPlayer123 when typing a mail recipient.
If needed, run:
/mailbox admin import player OldPlayer123

That creates full MailboxGUI player data from the shared network player index.

/mba networkindex

/mba networkindex is only useful in MailboxGUI network mode. It scans the current backend's local playerdata and adds known players to the shared MailboxGUI network player index.

• It helps typed recipient lookup find players across the network, especially legacy/old worlds where players may exist on one backend but have not used MailboxGUI yet.
• It does not send mail.
• It does not move mail data.
• It does not register mailboxes.
• It does not convert storage.
• It only indexes known local backend players into the shared network player index for lookup/import.
• Run it on each backend that has old/local playerdata you want indexed.
• Example: run it on Legacy so Live can type-recipient players who only played on Legacy.

Legacy player lookup example

If OldPlayer123 only played on Legacy, run:
/mba networkindex

Run that command on the Legacy backend.
After indexing, Live can find OldPlayer123 when an admin or player types their name as a mail recipient.

Network Reload Behavior

• /mba reload reloads the local backend.
• When network.enabled=true, it broadcasts a network reload request.
• Other backends reload their local config, language, sounds, and shared state.
• This is not a substitute for restarting after jar updates.

Update Command Warning

/mba update starts the update flow, and /mba update confirm downloads and stages the new jar for the next restart only on the backend where it is run. In Velocity-style or BungeeCord-style network setups, admins must run the update command on each backend server that has MailboxGUI installed, then restart each backend. It is not a network-wide jar deployment command.

Admin Tools in Network Mode

• Manage Registered Mailboxes shows server, world, and status when network mode is enabled.
• Registered Post Office Mailboxes shows server, world, and status when network mode is enabled.
• Same-backend mailboxes show Loaded or Unloaded.
• Remote-backend mailboxes show Remote Server.
• Server line is hidden in single-server mode.
• Removing registered mailboxes or PO boxes broadcasts cleanup so signs, paper notifications, and GUI lists refresh across backends.
• Admin inbox edits and inbox checks can sync refresh behavior across backends and refresh paper notifications.
• Existing old single-server data can be adopted by the current backend when network mode is enabled if the physical mailbox is loaded.

DiscBridge Network Support

• MailboxGUI-DiscBridge is a separate plugin.
• For normal standalone servers, use DiscBridge mode: LOCAL.
• For Velocity-style or BungeeCord-style network setups, install MailboxGUI on every backend.
• Install DiscordSRV and MailboxGUI-DiscBridge on only one backend.
• Set DiscBridge mode: NETWORK_NODE on that backend.
• DiscBridge does not run on the proxy itself.
• Other backends do not need DiscordSRV or MailboxGUI-DiscBridge.
• DiscBridge NETWORK_NODE listens to MailboxGUI network notification events and sends Discord notifications through the one local DiscordSRV instance.
• MailboxGUI-DiscBridge 1.1.1 or newer is recommended for the updated zh_cn and new zh_hk language files. MailboxGUI-DiscBridge 1.1.0 supports Book Letter delivery notifications and item-currency COD price text.
• Do not install DiscordSRV on every backend unless intentionally running separate DiscordSRV instances.

Troubleshooting

• Redis connection refused usually means the host is wrong or Redis is only bound to 127.0.0.1.
• In Pterodactyl/Docker, 127.0.0.1 inside plugin config usually means inside the Minecraft container, not the Ubuntu host.
• MySQL communications link failure usually means wrong host, bind address, firewall, or user permissions.
• If mail appears stale across backends, check Redis and network mode startup logs.
• If remote physical mailboxes show Unloaded, old data may need adoption or re-registration.
• If the update command is used in network mode, remember it only stages the local backend jar.

API Overview

MailboxGUI 5.1.0 or newer includes a public Java API for other plugins to send MailboxGUI mail programmatically. Integrations can send classic letters, Book Letters, packages, money mail, COD packages, package experience, item-currency COD prices, and delayed deliveries through MailboxGUI's normal storage, inbox, and notification systems, including network metadata when network mode is enabled.

• The API is registered through Bukkit ServicesManager.
• Integrations should softdepend or depend on MailboxGUI.
• Integrations should not manually edit MailboxGUI data files.
• The API respects config availability, package limits, blocked nested packages, blocked non-empty shulker boxes, economy/item-currency availability, and recipient policy.
• API package/COD sends respect active COD payment availability and config limits.
• API money and Vault-money COD behavior depends on active Vault/economy support. MailboxGUI 5.1.1 adds Vault2.0 custom currency amount parsing to player chat amount prompts.
• MailboxGUI-DiscBridge 1.1.0 uses the 5.1.0 API and delivery payload updates for Book Letters and item-currency COD price text. MailboxGUI-DiscBridge 1.1.1 or newer is recommended for the 5.1.1 language files.
• API-delivered money values use MailboxGUI money formatting when rendered as mail lore or messages.
• Network-aware notification metadata can include event and origin/current server details for integrations.

The public API entry points are:

• com.rismr1.mailboxgui.api.MailboxGUIApi
• com.rismr1.mailboxgui.api.MailboxGUIApiProvider

Core API methods include:

• sendLetter(LetterMailRequest request)
• sendBookLetter(BookLetterMailRequest request)
• sendPackage(PackageMailRequest request)
• sendMoney(MoneyMailRequest request)
• findRecipientByName(String playerName)
• hasMailboxData(UUID playerUuid)
• hasRegisteredMailbox(UUID playerUuid)
• getPackageContentLimit()
• getUncheckedMailCount(UUID playerUuid)
• getPendingLoginNotificationCount(UUID playerUuid)
• hasPendingMailNotification(UUID playerUuid)
• refreshMailNotification(UUID playerUuid)
• clearMailNotification(UUID playerUuid)

Request and result classes include:

• LetterMailRequest, BookLetterMailRequest, PackageMailRequest, MoneyMailRequest, and MailboxApiRecipient.
• MailboxSendResult, MailboxRecipientResult, and RecipientStatus.
• MailType values are LETTER, PACKAGE, and MONEY.
• MailDeliveryType includes BOOK_LETTER and COD_ITEM_CURRENCY_PAYMENT.
• Delivery events and network payloads include codPriceText for formatted COD prices.
• Delivery events can represent Book Letter deliveries and item-currency COD payment deliveries.
• Network notification concepts include eventId, notificationId, originServerId, originServerDisplayName, currentServerId, currentServerDisplayName, networkMode, localOrigin, syncOrigin, deliveryScope, and deliverySource.

Maven Dependency

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

plugin.yml Setup

plugin.yml

softdepend: [MailboxGUI]

• Use softdepend when your plugin can run without MailboxGUI but enables integration when present.
• Use depend when your plugin cannot function without MailboxGUI.
• Check for API availability before calling it.

Getting the API

import com.rismr1.mailboxgui.api.MailboxGUIApi;
import com.rismr1.mailboxgui.api.MailboxGUIApiProvider;

MailboxGUIApi mailboxApi = MailboxGUIApiProvider.get();

if (mailboxApi == null) {
    getLogger().warning("MailboxGUI API is not available.");
    return;
}

• MailboxGUIApiProvider.get() loads the registered service.
• It can return null if MailboxGUI is not installed/enabled or the service is not registered yet.
• Do API lookup after plugins are enabled, not too early in static initialization.

Recipient Model

MailboxApiRecipient represents an API delivery target.

MailboxApiRecipient byUuidAndName = MailboxApiRecipient.of(player.getUniqueId(), player.getName());
MailboxApiRecipient byUuid = MailboxApiRecipient.uuid(player.getUniqueId());
MailboxApiRecipient byName = MailboxApiRecipient.name("Rismr1");

• UUID is preferred when available.
• Name-only recipients can resolve through MailboxGUI data.
• Command integrations should use UUID/name when possible.

Recipient Policies

• REGISTERED_MAILBOX_ONLY: recipient must have MailboxGUI data and at least one registered mailbox.
• KNOWN_MAILBOXGUI_PLAYER: recipient must already exist in MailboxGUI data.
• CREATE_IF_MISSING: if a UUID is provided and data is missing, MailboxGUI can create MailboxGUI data for the recipient.

Sending a Letter

MailboxSendResult result = mailboxApi.sendLetter(
    LetterMailRequest.builder()
        .recipient(player.getUniqueId(), player.getName())
        .fromDisplayName("Quest Board")
        .message("Your quest reward is ready.")
        .recipientPolicy(RecipientPolicy.CREATE_IF_MISSING)
        .sourcePluginName("MyQuestPlugin")
        .notifyRecipients(true)
        .build()
);

• message cannot be blank for useful mail.
• fromDisplayName controls the visible sender name.
• sourcePluginName helps identify the integration source.
• notifyRecipients controls delivery notifications.
• deliveryDelaySeconds can be set for delayed mail.
• API delayed delivery remains persistent through MailboxGUI's delayed mail queue.

Sending a Book Letter

MailboxSendResult result = mailboxApi.sendBookLetter(
    BookLetterMailRequest.builder()
        .recipient(player.getUniqueId(), player.getName())
        .fromDisplayName("Quest Board")
        .title("Quest Update")
        .message("Page 1 of the player-facing book message.\nUse normal new lines for text.")
        .recipientPolicy(RecipientPolicy.CREATE_IF_MISSING)
        .sourcePluginName("MyQuestPlugin")
        .notifyRecipients(true)
        .build()
);

• BookLetterMailRequest creates an admin/server/API Book Letter.
• API Book Letters do not include Reply links.
• Reading context still controls Back to Inbox or Back to Player Inbox links.
• deliveryDelaySeconds can be set for delayed Book Letter delivery.

Sending a Package

ItemStack diamonds = new ItemStack(Material.DIAMOND, 3);

MailboxSendResult result = mailboxApi.sendPackage(
    PackageMailRequest.builder()
        .recipient(player.getUniqueId(), player.getName())
        .fromDisplayName("Dungeon Rewards")
        .addItem(diamonds)
        .experienceAmount(250)
        .recipientPolicy(RecipientPolicy.CREATE_IF_MISSING)
        .sourcePluginName("MyDungeonPlugin")
        .notifyRecipients(true)
        .build()
);

• contents cannot be empty.
• experienceAmount adds package XP if enabled.
• Package requests support contents, experienceAmount, codAmount, codItemCurrencyContents, senderUuid, returnCodPaymentToSender, deliveryDelaySeconds, notifyRecipients, recipientPolicy, and sourcePluginName.
• Package slot limit applies.
• getPackageContentLimit() returns the configured content slot count.
• Nested MailboxGUI packages are blocked.
• Non-empty shulker boxes are blocked when configured.
• If package experience is disabled, XP packages fail with DISABLED_BY_CONFIG.

Sending a COD Package

ItemStack sword = new ItemStack(Material.DIAMOND_SWORD, 1);
ItemStack diamonds = new ItemStack(Material.DIAMOND, 3);

MailboxSendResult result = mailboxApi.sendPackage(
    PackageMailRequest.builder()
        .recipient(buyer.getUniqueId(), buyer.getName())
        .fromDisplayName("Market Delivery")
        .senderUuid(seller.getUniqueId())
        .addItem(sword)
        .codAmount(1000.0)
        .addCodItemCurrency(diamonds)
        .returnCodPaymentToSender(true)
        .recipientPolicy(RecipientPolicy.CREATE_IF_MISSING)
        .sourcePluginName("MyShopPlugin")
        .notifyRecipients(true)
        .build()
);

• codAmount greater than 0 adds a Vault-money COD price.
• addCodItemCurrency or codItemCurrencyContents adds item-currency COD requirements.
• Vault/economy must be available for Vault-money COD. Item-currency COD must be enabled for item-currency prices.
• API COD sends respect COD payment availability.
• returnCodPaymentToSender(true) requires senderUuid.
• When enabled, accepted COD payments can return to the sender through money mail or direct deposit depending on MailboxGUI config.
• Declined COD package contents can return to the sender when senderUuid/return behavior is configured.
• Admin/server-origin COD packages without return opt-in behave as sink costs.

Sending Money Mail

MailboxSendResult result = mailboxApi.sendMoney(
    MoneyMailRequest.builder()
        .recipient(player.getUniqueId(), player.getName())
        .fromDisplayName("Event Rewards")
        .amount(500.0)
        .recipientPolicy(RecipientPolicy.CREATE_IF_MISSING)
        .sourcePluginName("MyEventsPlugin")
        .notifyRecipients(true)
        .build()
);

• Money mail requires money.enabled.
• Vault/economy must be available.
• amount must be greater than 0.
• MailboxGUI creates money mail in the player's inbox.

Delayed API Delivery

.deliveryDelaySeconds(300)

• -1 or not set uses the configured delay for that mail type.
• 0 means immediate delivery.
• Positive values queue persistent delayed delivery.
• Delayed deliveries are stored through MailboxGUI's delayed mail queue and survive server restart/shutdown.

Handling Results

if (!result.isSuccessful()) {
    for (MailboxRecipientResult recipientResult : result.getRecipientResults()) {
        if (!recipientResult.isSuccessful()) {
            getLogger().warning(recipientResult.getRecipientName()
                + " failed: "
                + recipientResult.getStatus()
                + " - "
                + recipientResult.getMessage());
        }
    }
}

MailboxSendResult includes:

• getRequestedRecipients()
• getDeliveredRecipients()
• getQueuedRecipients()
• getFailedRecipients()
• getWarnings()
• getRecipientResults()

RecipientStatus values include:

• DELIVERED
• QUEUED
• RECIPIENT_NOT_FOUND
• NO_REGISTERED_MAILBOX
• MAILBOX_DATA_MISSING
• INVALID_REQUEST
• INBOX_WRITE_FAILED
• DISABLED_BY_CONFIG
• ECONOMY_UNAVAILABLE
• TOO_MANY_CONTENTS
• EMPTY_PACKAGE
• NESTED_PACKAGE_BLOCKED
• NON_EMPTY_SHULKER_BLOCKED
• SERIALIZATION_FAILED

Recipient Lookup Helpers

• findRecipientByName(String playerName)
• hasMailboxData(UUID playerUuid)
• hasRegisteredMailbox(UUID playerUuid)
• getPackageContentLimit()

• findRecipientByName returns Optional<MailboxApiRecipient>.
• In network mode, recipient lookup can use shared MailboxGUI data and the network player index.
• hasRegisteredMailbox can enforce physical mailbox requirements before sending.
• getPackageContentLimit helps integrations avoid oversized packages before calling sendPackage.

Notification API

MailboxGUI notification API helpers let external plugins and bridge modules check and manage player mail notification state without manually editing MailboxGUI data. In 5.1.0, network notification events can carry origin/current server metadata and codPriceText for multi-backend delivery.

• getUncheckedMailCount(UUID playerUuid): Returns the number of inbox items marked as new/unseen.
• getPendingLoginNotificationCount(UUID playerUuid): Returns queued login notification totals for the player.
• hasPendingMailNotification(UUID playerUuid): Returns true when visual, login, or unchecked-mail notification state exists.
• refreshMailNotification(UUID playerUuid): Asks MailboxGUI to reconcile/update the player's physical notification.
• clearMailNotification(UUID playerUuid): Clears tracked notification state safely through the plugin API.

Network event metadata can include:

• eventId / notificationId
• originServerId and originServerDisplayName
• currentServerId and currentServerDisplayName
• networkMode, localOrigin, and syncOrigin
• deliveryScope and deliverySource

MailboxGUI-DiscBridge uses these event/network concepts for NETWORK_NODE notifications.

API Integration Best Practices

• Prefer UUID + name recipients.
• Use sourcePluginName.
• Handle partial failures.
• Check package limits.
• Avoid sending nested MailboxGUI packages.
• Avoid non-empty shulker boxes if blocked.
• Respect disabled features.
• Use softdepend unless MailboxGUI is required.
• Never edit MailboxGUI data files directly.
• Use MailboxGUI's API instead of constructing raw inbox items manually.
• For network setups, treat notification origin/current server metadata as informational context and avoid assuming the event was produced on the same backend that handles it.

API Troubleshooting

• API provider returns null.
• MailboxGUI is not installed/enabled.
• Missing softdepend/depend.
• Recipient not found.
• Recipient has no registered mailbox when policy requires it.
• Package too large.
• Package empty.
• Vault-money COD requires Vault/economy; item-currency COD requires item-currency COD to be enabled.
• Money mail requires Vault/economy.
• Delayed delivery returns QUEUED, not DELIVERED.
• Integration used name-only recipient with CREATE_IF_MISSING and expected data creation without UUID.

PlaceholderAPI Overview

MailboxGUI includes optional PlaceholderAPI support. When PlaceholderAPI is installed and enabled, MailboxGUI registers the %mailboxgui_*% placeholder expansion. These placeholders can be used by PlaceholderAPI-compatible plugins such as scoreboards, hologram plugins, tab/list plugins, chat plugins, menu plugins, and server information displays.

• PlaceholderAPI is optional.
• MailboxGUI works without PlaceholderAPI.
• Placeholders only work when PlaceholderAPI is installed and the hook registers successfully.
• All MailboxGUI placeholders use the mailboxgui identifier.
• The placeholder format is %mailboxgui_<placeholder>%.

Server and Storage Placeholders

Player Mailbox Placeholders

These placeholders require a player context. If used somewhere without a player, they may return 0 or no depending on the placeholder.

Pending Mail Placeholders

Placeholder Usage Examples

Scoreboard-style examples

Mailbox: %mailboxgui_mailbox_registered%
Inbox: %mailboxgui_inbox_total%
New Mail: %mailboxgui_pending_total%

Admin/server display examples

Storage: %mailboxgui_storage_type%
Queued Mail: %mailboxgui_delayed_mail_queued%
Registered Mailboxes: %mailboxgui_registered_mailboxes%
Post Office Boxes: %mailboxgui_postoffice_mailboxes%

Exact usage depends on the PlaceholderAPI-compatible plugin being configured. MailboxGUI only provides the placeholder values.

Placeholder Troubleshooting

• PlaceholderAPI is not installed.
• PlaceholderAPI is installed but not enabled.
• MailboxGUI loaded before PlaceholderAPI incorrectly or the hook did not register.
• The placeholder is typed incorrectly.
• The placeholder is used without a player context.
• The scoreboard/hologram/menu plugin does not support PlaceholderAPI in that field.
• Use /papi parse if available to test placeholder output.
• Check console for "PlaceholderAPI hook enabled" or hook registration messages.

Player Permissions

Use these permissions for normal player-facing mailbox access.

• mailboxgui.player.use: Allows normal player access to MailboxGUI commands and player workflows.
• mailboxgui.player.postoffice.pobox: Allows opening public Post Office boxes when post-office.mailboxes.allow-any-player-open is false.
• mailboxgui.player.postoffice.npc: Allows opening mailbox access through marked Citizens Post Office NPCs.

Admin Tools Permissions

Use these permissions to control MailboxGUI admin commands and GUI tools.

Base/admin

• mailboxgui.admin: Full access to all MailboxGUI admin commands, tools, import, reload, conversion, cleanup, send, item templates, and admin functions.
• mailboxgui.admin.reload: Allows reloading MailboxGUI config and language files.
• mailboxgui.admin.import: Allows importing player serverdata into MailboxGUI data.
• mailboxgui.admin.convert: Allows converting MailboxGUI storage between YAML, SQLite, and MySQL.
• mailboxgui.admin.networkindex: Allows indexing local backend playerdata into shared network player data when network mode is enabled.
• mailboxgui.admin.update: Allows update checks, update preparation, and update confirmation through the website release system.
• mailboxgui.admin.clean: Allows generated MailboxGUI backup cleanup after confirmation.

Admin command/API-backed send

• mailboxgui.admin.send: Access to all admin command/API-backed send shortcuts.
• mailboxgui.admin.send.letter: Allows admin Classic Letter and Book Letter send commands, including /mba sl and /mba sla.
• There is no separate mailboxgui.admin.send.bookletter permission in the 5.1.0 source.
• mailboxgui.admin.send.package: Allows admin package send commands.
• mailboxgui.admin.send.cod: Allows admin COD package send commands.
• mailboxgui.admin.send.money: Allows admin money mail send commands.

Item templates

• mailboxgui.admin.itemtemplate: Access to item template commands.
• mailboxgui.admin.itemtemplate.save: Allows saving the held main-hand item as a template.
• mailboxgui.admin.itemtemplate.delete: Allows deleting item templates.
• mailboxgui.admin.itemtemplate.list: Allows listing item templates.
• mailboxgui.admin.itemtemplate.give: Allows giving a saved item template to a player.

Admin tools

• mailboxgui.admin.tools.*: Access to all MailboxGUI admin GUI tools.

Admin send mail

• mailboxgui.admin.tools.sendmail.*: Access to all admin send-mail options.
• mailboxgui.admin.tools.sendmail.letter.*: Access to all admin letter send options.
• mailboxgui.admin.tools.sendmail.letter.allmailboxes: Send admin letters to all mailbox players.
• mailboxgui.admin.tools.sendmail.letter.onlinemailboxes: Send admin letters to online mailbox players.
• mailboxgui.admin.tools.sendmail.letter.selectrecipient: Send admin letters to selected recipients.
• mailboxgui.admin.tools.sendmail.package.*: Access to all admin package send options.
• mailboxgui.admin.tools.sendmail.package.allmailboxes: Send admin packages to all mailbox players.
• mailboxgui.admin.tools.sendmail.package.onlinemailboxes: Send admin packages to online mailbox players.
• mailboxgui.admin.tools.sendmail.package.selectrecipient: Send admin packages to selected recipients.
• mailboxgui.admin.tools.sendmail.money.*: Access to all admin money send options.
• mailboxgui.admin.tools.sendmail.money.allmailboxes: Send admin money to all mailbox players.
• mailboxgui.admin.tools.sendmail.money.onlinemailboxes: Send admin money to online mailbox players.
• mailboxgui.admin.tools.sendmail.money.selectrecipient: Send admin money to selected recipients.

Admin inbox check

• mailboxgui.admin.tools.inboxcheck.*: Access to all admin inbox check controls.
• mailboxgui.admin.tools.inboxcheck.see: View player inboxes.
• mailboxgui.admin.tools.inboxcheck.edit: Edit player inboxes.

Registered mailbox management

• mailboxgui.admin.tools.managemailbox.*: Access to all mailbox management controls.
• mailboxgui.admin.tools.managemailbox.see: View registered player mailboxes.
• mailboxgui.admin.tools.managemailbox.register: Register a mailbox for a specific player through admin tools or command.
• mailboxgui.admin.tools.managemailbox.unregister: Unregister player mailboxes through admin tools or command.

Storage Permissions

Use these permissions for storage conversion and backup maintenance.

• mailboxgui.admin.convert: Allows converting MailboxGUI storage between YAML, SQLite, and MySQL.
• mailboxgui.admin.networkindex: Allows /mba networkindex in network mode.
• mailboxgui.admin.clean: Allows cleaning generated backup files after confirmation.
• mailboxgui.admin: Includes all admin access, including storage conversion and cleanup.

Post Office Permissions

Use these permissions to control player PO Box access and admin Post Office tools.

Player permissions

• mailboxgui.player.postoffice.pobox: Allows players to open public Post Office boxes when post-office.mailboxes.allow-any-player-open is false.
• mailboxgui.player.postoffice.npc: Allows players to open mailbox access through Post Office NPCs.

Admin permissions

• mailboxgui.admin.tools.postoffice.*: Access to all Post Office registration tools.
• mailboxgui.admin.tools.postoffice.mailbox.*: Access to all Post Office box registration tools.
• mailboxgui.admin.tools.postoffice.mailbox.set: Allows registering Post Office boxes.
• mailboxgui.admin.tools.postoffice.mailbox.remove: Allows removing Post Office boxes through selector mode or registered list actions.
• mailboxgui.admin.tools.postoffice.mailbox.list: Allows viewing registered Post Office boxes.
• mailboxgui.admin.tools.postoffice.npc.*: Access to all Post Office NPC tools.
• mailboxgui.admin.tools.postoffice.npc.set: Allows marking Citizens NPCs as Post Office NPCs.
• mailboxgui.admin.tools.postoffice.npc.remove: Allows removing the Post Office trait from Citizens NPCs.

NPC Support Permissions

Use these permissions to control access to marked Citizens Post Office NPCs and the related admin tools.

Player permission

• mailboxgui.player.postoffice.npc: Allows players to open mailbox access through marked Post Office NPCs.

Admin permissions

• mailboxgui.admin.tools.postoffice.npc.*: Access to all Post Office NPC tools.
• mailboxgui.admin.tools.postoffice.npc.set: Allows admins to mark Citizens NPCs as Post Office NPCs.
• mailboxgui.admin.tools.postoffice.npc.remove: Allows admins to remove the Post Office marker from Citizens NPCs.

Related admin permission

• mailboxgui.admin.tools.postoffice.*: Access to Post Office registration tools, including Post Office mailbox tools and NPC tools.

Quick Troubleshooting Checklist

Start with the basics before assuming data or plugin failure.

• Confirm the server fully restarted after installing or updating MailboxGUI.
• Check console for MailboxGUI startup errors.
• Confirm the plugin is enabled.
• Confirm the correct server version is being used.
• Confirm required hooks such as Vault, economy, Citizens, or Dynmap are installed only when their related feature is needed.
• Confirm permissions are assigned through the server's permission plugin.
• Confirm config.yml was not broken by invalid YAML formatting.
• Confirm MailboxGUI 5.1.1 configs are synchronized to config-version: 12 and language files to file-version: 14.
• Confirm 5.1.1 mail data is at mail data version 5.
• Confirm the feature is enabled in config.yml.

Plugin Does Not Start

Common startup problems include wrong Java/server compatibility, broken YAML formatting, missing files, or using plugin reload instead of a full restart after a major update.

• Wrong Java/server compatibility.
• Broken config.yml YAML formatting.
• Missing dependency for a feature being tested.
• Plugin jar not placed in the server plugins folder.
• Server used plugin reload instead of a full restart after a major update.
• Startup error appears in console.

Example startup configuration error

[MailboxGUI] Enabling MailboxGUI...
[MailboxGUI ERROR] Failed to load configuration.
[MailboxGUI ERROR] Check config.yml spacing, quotes, and list formatting.

This is an example style of problem to look for. Exact wording may vary by version.

Mailbox Is Not Detected

• Player mailbox must use a valid physical structure.
• Player mailbox structure must be a valid single chest or barrel with a sign attached to the front face of the chest/barrel.
• Double chests and trapped chests are not valid player mailboxes.
• The chest/barrel container is not valid.
• The sign must be attached to the front face of the chest/barrel.
• Region protection may block interaction or registration.
• Player may lack permission.
• The mailbox may already be registered or owned by another player.

Post Office Box Does Not Work

• post-office.enabled must be true.
• post-office.mailboxes.enabled must be true.
• PO Box structure is a single chest or barrel with a sign attached to the front face of the chest/barrel.
• PO Boxes do not use the fence-post base.
• Public PO Boxes are access points to the player's own mailbox menu, not shared public inboxes.
• PO Boxes are not registered to individual players.
• Current PO Box signs say Public Access / Right Click by default, so older screenshots or custom configs with numbered signs may differ.
• The box must be registered through Admin Tools.
• If allow-any-player-open is false, players need mailboxgui.player.postoffice.pobox.
• The saved world/chunk may not be loaded.
• Region protection can block right-click interaction.

Letters Do Not Send

• letter.enabled must be true.
• Sender must have normal MailboxGUI access.
• Recipient must be a valid delivery target.
• If the player typed cancel during the prompt, sending was cancelled.
• Language customization may change button names compared to screenshots.
• Delivery delay may make the letter arrive later when configured.
• Admin command/API delivery may resolve recipients through online players, MailboxGUI data, or main-world playerdata for joined-before players.
• If a command recipient is not found, command send fails instead of sending partial mail.

Packages Do Not Send or Open

• package.enabled must be true.
• Package cannot be empty.
• MailboxGUI packages cannot be placed inside other packages.
• Non-empty shulker boxes are blocked when package.deny-loaded-shulker-box is true.
• Recipient must be valid.
• Command/API package was too large for the configured package slot count.
• Command item template ID was missing or invalid.
• Player may not have enough inventory space when cancelling or withdrawing items.
• Regular packages open into the Package Contents GUI where the recipient manually withdraws items.
• If a package was partially emptied, remaining contents can be saved back into the inbox package.
• Delayed command/API package delivery can return queued behavior instead of immediate delivery.

Book Letters Do Not Work

• letter.enabled must be true.
• The player must follow Send Mail, Letter, Book Letter, then select a recipient.
• The temporary Book and Quill must be right-clicked manually from the selected hotbar slot.
• Sign and Close sends the Book Letter. Done/Escape keeps the draft open and saves progress.
• Typing cancel in chat cancels the draft, removes the temporary book, and restores the original hotbar item.
• While a draft is active, other inventory, item, block, and entity interactions are blocked until the draft is sent or canceled.
• Player-sent Book Letters include Reply. Admin/server/API Book Letters do not include Reply.
• Admin inbox check hides Reply and uses Back to Player Inbox when reading a player Book Letter.

COD Packages Do Not Work

• package.cash-on-demand.enabled must be true.
• At least one payment option must be available: Vault money or item currency.
• Vault-money COD requires Vault and a compatible economy plugin.
• Item-currency COD requires package.cash-on-demand.item-currency.
• If the COD button is missing or disabled, check package.cash-on-demand.enabled and the configured COD payment options.
• Command/API COD fails when the requested payment type is unavailable.
• Recipient must have enough money, items, and/or XP to accept the COD package.
• Sender must type a valid COD price expression.
• Typing off, none, or 0 removes COD.
• Typing cancel returns without changing COD.
• Unpaid COD packages open into Package Preview, not normal Package Contents.
• If a COD package cannot be previewed, accepted, or declined, the required COD payment support may be unavailable.
• Admin-origin COD packages act as sink costs unless r:<returnPlayer> or API return behavior is configured.

Money Mail Does Not Work

• money.enabled must be true.
• Vault must be installed.
• A compatible economy plugin must be hooked.
• If Money Mail is missing from Send Mail, check money.enabled and Vault/economy availability.
• Amount must be greater than 0.
• Sender must have enough money.
• Recipient must be valid.
• Command recipients can fail when the player has not joined before and cannot be found in main-world playerdata.
• Economy deposit can fail if the economy plugin is not available or rejects the transaction.
• If money amounts look wrong, check money.display-format-mode, money.custom-format, and money.amount-format.
• Delayed money mail may be queued instead of delivered immediately.

NPC Support Does Not Work

• Citizens must be installed and enabled.
• MailboxGUI must detect the Citizens API.
• The NPC must be marked through Admin Tools -> Post Office Registration -> NPC Set / Remove.
• Player needs mailboxgui.player.postoffice.npc.
• Admin needs mailboxgui.admin.tools.postoffice.npc.set or remove.
• If Citizens is missing, NPC tools show Citizens unavailable.
• Dynmap marker issues do not stop NPC mailbox access.
• If Dynmap NPC markers remain stale after NPC deletion, reload/restart or wait for the consistency check; Citizens/Dynmap compatibility still matters.

Dynmap Markers Do Not Show

• dynmap.enabled must be true.
• The relevant marker group must be enabled.
• Dynmap must be installed and compatible with the server version.
• Marker refresh can happen on startup/reload/register/unregister depending on config.
• Dynmap markers are not supported on Minecraft 26.1.x or 26.2.x. MailboxGUI can still run without Dynmap marker support.

Storage or Data Looks Missing

• storage.type may point to a different backend than the one containing existing data.
• Do not change storage.type manually to move data.
• Use /mailbox admin convert current to verify the active backend, then /mailbox admin convert <YAML|SQLITE|MYSQL> to convert to the selected backend.
• YAML data is under plugins/MailboxGUI/data/playerdata and plugins/MailboxGUI/data/postofficedata.
• SQLite data defaults to plugins/MailboxGUI/data/data.db.
• Delayed mail queue data is handled through the active storage provider.
• If old generated backups need cleanup, use /mailbox admin clean only after verifying mail data works.
• MySQL requires a valid database connection.
• MySQL startup failure falls back to SQLite.
• Always check backups before assuming data is gone.

Permissions Problems

• Players need mailboxgui.player.use for normal /mailbox access.
• Some public Post Office access may require mailboxgui.player.postoffice.pobox or mailboxgui.player.postoffice.npc.
• Admin GUI features require specific mailboxgui.admin.tools.* permissions.
• Admin command send shortcuts require mailboxgui.admin.send or the specific send permission.
• Item template commands require mailboxgui.admin.itemtemplate or the specific item template permission.
• mailboxgui.admin gives full admin access.
• If a button is missing or does nothing, confirm the player/admin has the correct permission.
• Permission plugins may require a server restart or permission reload after changes.

Config YAML Problems

• Use spaces, not tabs.
• Keep quotes around values that contain color codes or special characters.
• YAML lists must use proper indentation.
• Broken YAML can prevent config loading.
• If a config option is missing, the synchronizer can add defaults while preserving matching existing settings.

YAML indentation example

package:
  enabled: true
  size-in-rows: 3
  cash-on-demand:
    enabled: true
    send-reward-in-mail: true

When to Ask for Support

When asking for support, include:

• MailboxGUI version.
• Server version.
• Platform: Spigot, Paper, Purpur, etc.
• Relevant plugins: Vault, economy plugin, Citizens, Dynmap.
• Full console error.
• What action caused the issue.
• Whether the server was restarted after install/update.
• Current storage.type.
• Screenshots if the issue is GUI or structure related.