MailboxGUI Wiki

What MailboxGUI Does

MailboxGUI adds a server mail system for Minecraft Paper and Spigot 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 4.1.0 adds public API integration, API-backed admin send commands, automatic playerdata import behavior for typed recipient and admin command send flows, and uses config-version: 8.

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.

Recommended Dependencies and Hooks

• Vault: needed for economy features such as money mail, COD payments, and paid post office actions when enabled.
• Economy plugin: required alongside Vault if the server wants economy-based mail features.
• 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. MailboxGUI does not require Dynmap to run. Note: Dynmap marker support is currently unavailable on Minecraft 26.1.x because Dynmap does not yet provide a compatible build for that version range.
• 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.
• Storage: fresh installs are designed around SQLite by default, while existing legacy YAML installs can remain on YAML safely during upgrade. MySQL is available for servers that want database-backed storage.

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 COD.
• Confirm players and admins have the permissions they need.
• Confirm physical mailbox setup works before announcing it to players.

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 COD and money mail only after economy support is confirmed.
• 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.
• Player unregister mode lets the player select one of their registered mailboxes.
• 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.

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.
• This is useful when an admin wants to prepare MailboxGUI data for players before they interact with mailboxes.
• MailboxGUI 4.1.0 also uses auto-import in typed recipient and admin command send flows where a player has joined the server before.
• PlayerDataImportManager reads the first loaded world's playerdata folder.

Storage Conversion Commands

Storage conversion

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

Examples:

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

• Requires mailboxgui.admin.convert or mailboxgui.admin.
• Source type must match the active storage type.
• Same-type conversion is refused.
• Conversion creates backups.
• Conversion to MYSQL validates MySQL first.

Admin Send-Mail Commands

Admin send shortcuts

/mba sl <recipient[,recipient2]> [from] '<message>' [--from <sender>] [--delay <seconds>]

/mba sp <recipient[,recipient2]> [from] <item:amount> [item:amount...] [--from <sender>] [--delay <seconds>]

/mba scod <recipient[,recipient2]> [from] <codPrice> [r:<returnPlayer>] <item:amount> [item:amount...] [--from <sender>] [--delay <seconds>]

/mba sm <recipient[,recipient2]> [from] <amount> [--from <sender>] [--delay <seconds>]

• sl sends a 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.
• from can be passed positionally or through --from.
• --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, or main-world server playerdata if the player has joined before.
• 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 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.send
• mailboxgui.admin.send.letter
• 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 physical mailbox is built with a fence post, a single chest on top, and a sign attached to the front of the chest.

The fence post is the base. The single chest is the storage and interaction point. The sign must be attached to the front face of the chest, not floating nearby or placed on the ground. Keep the structure simple and recognizable so players understand it is a mailbox.

Materials Needed

• 1 fence post
• 1 single chest
• 1 sign
• Optional decoration blocks around it, as long as the core mailbox structure remains valid.

Step-by-Step Build

1. Place the fence post where the mailbox should stand.
2. Place one single chest directly on top of the fence post.
3. Attach the sign to the front of the chest.
4. Keep the sign on the chest face, not beside the chest.
5. Make sure the chest 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. Use the server's MailboxGUI interaction or registration flow according to the server's permissions and configuration.

Correct vs Incorrect Setup

Common mailbox build mistakes include:

• Using a double chest instead of a single chest.
• Placing the sign on the ground instead of attaching it to the front of the chest.
• Attaching the sign to the wrong side if the server or admin expects a specific front-facing setup.
• Missing the fence post under the chest.
• Blocking access to the chest 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 chests, 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.

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.

Sending a Letter

1. Open the mailbox or mail sending interface.
2. Choose the letter sending option.
3. Select the recipient.
4. Write the letter message or body.
5. Confirm and send the letter.
6. 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. In 4.1.0, typed name lookup can auto-import players from main-world playerdata when they have joined the server before.

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.

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.

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.

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

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 economy and COD support are 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.

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.
• Vault must be installed and hooked.
• A compatible economy plugin must be available.
• The sender and recipient must have the needed MailboxGUI access based on the server's permissions.
• The recipient must have enough money to accept the COD package.

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

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 has Accept, Cancel, and Decline/Return controls. Cancel returns to the inbox without making a payment or returning the package.

Accepting a COD Package

Accept checks the recipient's economy balance. If the recipient cannot afford the COD price, the package remains unpaid. If the recipient can afford it, the COD price is withdrawn.

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. If true, the sender receives the payment as MailboxGUI money mail. If false, the money is deposited directly into the sender's economy account.

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. The API equivalent is setting senderUuid with returnCodPaymentToSender(true).

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 Vault or economy support is unavailable.
• COD is disabled in config.
• Recipient does not have enough money.
• Sender typed an invalid COD amount.
• 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.
• 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.
• 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.

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.

Entering the Amount

After selecting the recipient, the player types the amount in chat. The value must be greater than 0. The amount parser accepts normal decimals and also handles dollar signs and commas, such as 100, 100.50, $100, or 1,000.

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.

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.

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 Offices 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 Post Office box opens the normal MailboxGUI menu for the player using it. It is a public access point, not a separate shared inbox.

Players use the PO Box to access their own mail features. 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 with a sign attached to the front of the chest.

• The chest must remain a single chest.
• The sign must be attached to the front face of the chest.
• The admin can select either the chest or the attached sign during registration.
• The plugin must be able to resolve the sign/chest pair.
• Decorative blocks can be added around it as long as the chest 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 chest 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.

Sign Format and Numbering

Registered PO Box signs are updated using post-office.mailboxes.sign-format. The sign supports %postofficename% and %number%.

The default format includes the MailboxGUI header, the Post Office name, and PO Box number. PO Box numbering is grouped by Post Office name. Removing a PO Box can renumber the remaining boxes for that Post Office when renumber-after-remove is enabled.

Player Access

Players right-click a registered Post Office chest or sign. If allowed, MailboxGUI opens the main mailbox menu. The player is accessing their own mail 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.
• 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, and loaded/unloaded physical status.

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

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 chest/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. Normal players cannot break registered PO Box blocks directly because they are protected.

Protection and Safety

• Registered PO Box chests 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 chest is not a valid single chest.
• The sign is not attached to the front of the chest.
• 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 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.

NPC Support vs Post Office Boxes

Post Office NPCs and Post Office boxes both provide public access to MailboxGUI. Post Office boxes are physical chest/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.
• 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, and each type opens an audience selector.

• 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 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 an audience. For bulk audiences, the admin types the message in chat after choosing the audience. 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.

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 COD/economy support is available.
• Admin-origin COD packages act as sink costs and do not pay an admin/server sender.
• 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.

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.

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 letters or money mail removes them, and clicking a package opens Admin Package Action. The target inbox is saved when edits are made.

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.

• 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.
• Confirming removal unregisters that saved mailbox and clears the sign if 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.
• /mailbox admin import player <name...> imports player data into MailboxGUI data.
• /mailbox admin convert <YAML|SQLITE|MYSQL> to <YAML|SQLITE|MYSQL> runs storage conversion.
• /mba sl, /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/economy support is missing.
• 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.

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.

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

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.

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.
• Convert from the active type to the target type.
• Verify data after conversion before deleting old backups or old data.

Storage Conversion Command

Storage conversion command

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

Examples:

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

• The source type must match the configured active storage type.
• Same-type conversion is refused.
• Conversion requires mailboxgui.admin.convert or mailboxgui.admin.
• Conversion to MYSQL validates MySQL before copying data or changing config.

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/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/
    └── 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

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 only when you have a maintained database server and want database-backed storage.
• 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.
• 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.

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

Admin command/API-backed send

• mailboxgui.admin.send: Access to all admin command/API-backed send shortcuts.
• mailboxgui.admin.send.letter: Allows admin letter send commands.
• 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 maintenance.

• mailboxgui.admin.convert: Allows converting MailboxGUI storage between YAML, SQLite, and MySQL.
• mailboxgui.admin: Includes all admin access, including storage conversion.

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.

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

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: '&c[&aMailboxGUI&c]'
    line-2: '%player%'
    line-3: '&bMailbox &c#&6%number%'
    line-4: ''

chat-mail-notifications:
  offline-summary-mode: SIMPLE

  online-delivery-alerts: true

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: '&c[&aMailboxGUI&c]'
      line-2: '%postofficename%'
      line-3: '&6PO Box #%number%'
      line-4: ''

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

    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

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

update-checker:
  enabled: true

  check-on-startup: true

  notify-on-join: true

  notify-permission: "mailboxgui.admin"

config-version

config-version

config-version: 8

• Default: 8
• 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.
• 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.
• MailboxGUI validates MySQL before startup/conversion use.
• If startup validation fails, MailboxGUI falls back to SQLITE.

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: '&c[&aMailboxGUI&c]'
    line-2: '%player%'
    line-3: '&bMailbox &c#&6%number%'
    line-4: ''

• Controls the four lines written to registered physical player mailbox signs.
• Supports color codes using &.
• Supports placeholders: %player%, %number%.
• line-4 can be blank.

Offline Summary Mode

Offline Summary Mode

chat-mail-notifications:
  offline-summary-mode: SIMPLE

• Default: SIMPLE
• Possible values: SIMPLE, ADVANCED, OFF.
• SIMPLE: sends a compact login summary with total pending mail.
• ADVANCED: sends a more detailed login summary by mail type.
• OFF: disables offline login mail summary messages.

Online Delivery Alerts

Online Delivery Alerts

chat-mail-notifications:
  online-delivery-alerts: true

• Default: true
• Possible values: true or false.
• true: players receive chat alerts when mail arrives while they are online.
• false: online delivery chat alerts are disabled.
• This does not disable inbox mail itself.

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: '&c[&aMailboxGUI&c]'
      line-2: '%postofficename%'
      line-3: '&6PO Box #%number%'
      line-4: ''

• Controls the four sign lines for registered Post Office boxes.
• Supports color codes using &.
• Supports placeholders: %postofficename%, %number%.
• line-4 can be blank.

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.
• Minecraft 26.1.x marker support is unavailable when Dynmap has no compatible build for that version range.
• 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
    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
  admin-server-name: '&a&lServer'

Update Checker Configuration

Update Checker Configuration

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

API Overview

MailboxGUI 4.1.0 includes a public Java API for other plugins to send MailboxGUI mail programmatically. Integrations can send letters, packages, money mail, COD packages, package experience, and delayed deliveries through MailboxGUI's normal storage, inbox, and notification systems.

• 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 availability, and recipient policy.

The public API entry points are:

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

Core API methods include:

• sendLetter(LetterMailRequest request)
• sendPackage(PackageMailRequest request)
• sendMoney(MoneyMailRequest request)
• findRecipientByName(String playerName)
• hasMailboxData(UUID playerUuid)
• hasRegisteredMailbox(UUID playerUuid)
• getPackageContentLimit()

Request and result classes include:

• LetterMailRequest, PackageMailRequest, MoneyMailRequest, and MailboxApiRecipient.
• MailboxSendResult, MailboxRecipientResult, and RecipientStatus.
• MailType values are LETTER, PACKAGE, and MONEY.

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.

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, 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);

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

• codAmount greater than 0 creates a COD package.
• Vault/economy must be available.
• 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>.
• hasRegisteredMailbox can enforce physical mailbox requirements before sending.
• getPackageContentLimit helps integrations avoid oversized packages before calling sendPackage.

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.

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.
• COD requires Vault/economy.
• 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 4.1.0 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.

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 4.1.0 configs are synchronized to config-version: 8.
• 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 is a fence post, a single chest on top, and a sign attached to the front of the chest.
• Double chests and trapped chests are not valid player mailboxes.
• The sign must be attached to the front of the chest.
• 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 with a sign attached to the front of the chest.
• PO Boxes do not use the fence-post base.
• 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.

COD Packages Do Not Work

• package.cash-on-demand.enabled must be true.
• Vault must be installed.
• A compatible economy plugin must be hooked.
• Command/API COD also fails when economy is unavailable.
• Recipient must have enough money to accept the COD package.
• Sender must type a valid positive amount.
• Typing off, none, or 0 removes COD.
• Typing cancel returns without changing COD.
• Unpaid COD packages open into Package Preview, not normal Package Contents.
• Admin-origin COD packages act as sink costs and do not pay an admin/server sender.

Money Mail Does Not Work

• money.enabled must be true.
• Vault must be installed.
• A compatible economy plugin must be hooked.
• 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.
• 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.

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.
• Minecraft 26.1.x marker support depends on Dynmap having a compatible release build. 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 <YAML|SQLITE|MYSQL> to <YAML|SQLITE|MYSQL>.
• 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.
• 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: Paper, Spigot, 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.