MailboxGUI Wiki

MailboxGUI turns physical mailbox builds into persistent personal inboxes. Players send paper and book letters, item/XP packages, COD packages and economy money mail; administrators can manage deliveries, shared staff mail, automated schedules and public access points. Both editions provide the full standalone mail system. Premium adds shared multi-backend infrastructure rather than requiring a purchase to use ordinary mail.

This guide documents the 6.1.0 implementation and is the site’s default MailboxGUI wiki. Check the download page for the editions and builds currently available; marketplace linking readiness is described separately below.

For 6.1.0 / 2.1.0, Free must pair with Free and Premium must pair with Premium. Buying one Premium product does not include the other. DiscBridge 2.1.0 requires the MailboxGUI 6.1.0-era integration and a compatible API protocol; do not install it as a drop-in addon for 5.1.1 or 6.0.0. Check future release requirements before mixing versions.

The two columns compare the same capability row by row. “Premium” identifies a paid plugin feature; the optional resource pack and DiscBridge Premium are separate products and do not automatically license one another.

1. Back up the existing plugin folder and selected database before changing editions or versions. For a new server, confirm the server/Java requirements first.
2. Download the correct edition’s final MailboxGUI jar and place one MailboxGUI jar in plugins/. Do not use a Maven original-* artifact or keep duplicate Free/Premium jars.
3. Start the server through your usual maintenance process. Inspect the console for a successful load and generated plugins/MailboxGUI/ files.
4. Review config.yml: default storage is SQLITE at data/data.db. Leave Premium network.enabled false for standalone use. Configure optional integrations only if installed.
5. Give staff appropriate permissions, run /mb guide, create/register a mailbox, then test a paper letter and a package. Enable command-only access only if desired.
6. Edit existing YAML using spaces and preserve keys/types. Run /mba reload for supported configuration changes. Root-language registration and storage migration need the separate procedures below.

mailbox:
  command-open:
    enabled: true
    worlds:
      enabled: true
      whitelist: [world, survival]
package:
  player-command-send:
    enabled: true
money:
  player-command-send:
    enabled: true

These are configuration fragments, not replacements for the full file. Permissions do not enable a feature that its configuration disables. World whitelists are local access rules; they are not Premium backend targeting.

Sending routes and exact new-install defaults

Player enablement, player-command enablement, Admin Tools sending and administrator/console sending are different routes. The table uses values read directly from the bundled config.yml, not example overrides. API and scheduled sending use their own validated request/task path rather than the Admin Tools or admin-command switches. Disabling new sending does not delete existing mail or prevent normal receiving/claiming.

World restrictions use each route’s worlds.enabled and worlds.whitelist. Enable a whitelist before expecting it to take effect; the applicable focused world-bypass permission does not bypass a disabled send route. No default expiration-duration setting exists in config.yml: choose expiration through Admin Tools, --expire, a scheduled task, or an API request.

Build and register a personal mailbox

1. Use /mb guide to see designs available on the running server. Use /mb kit or /mb kit <kit-id> if kits are enabled and your usage allowance remains.
2. For a classic personal design, place a fence, a single supported body block above it, and a regular wall sign attached to the front. Use a single chest, not a double chest.
3. For a wall-shelf design, mount a supported shelf against a wall and align the regular wall sign below it with the same mounting wall. This design does not require a fence.
4. Run /mb register and follow the selection prompt for the build. The plugin writes the configured sign format; you do not need to invent a special marker word.
5. Right-click the registered mailbox to open your inbox. Use /mb unregister and the prompted selection workflow to remove a personal registration.

Use regular signs, not hanging signs. Newer bodies and wood types cannot be enabled on a server that lacks their materials. The guide only offers supported designs; an entire kit is unavailable if any required material is unsupported.

Kits, limits and indicators

The default mailbox limit is 5 per player. Kits are named material lists, not restrictions on which valid designs can be registered. Default enabled examples include Classic_Mailbox, Classic_Barrel, Copper_Chest and Wall_Shelf_Mailbox; newer-server kits may be unavailable on older versions. Disabled shulker examples do not mean other colors are unsupported. Usage defaults to 1; 0 means unlimited. Reminder frequency 0 disables periodic reminders even when the notification flag is true.

mailbox:
  max-mailboxes-per-player: 5
  kit:
    enabled: true
    usage: 1
    notification: true
    notification-frequency-minutes: 0
    kits:
      Classic_Mailbox:
        enabled: true
        kit-contents:
          - CHEST:1
          - OAK_SIGN:1
          - OAK_FENCE:1
      Classic_Barrel:
        enabled: true
        kit-contents:
          - BARREL:1
          - DARK_OAK_SIGN:1
          - DARK_OAK_FENCE:1
      Copper_Chest:
        enabled: true
        kit-contents:
          - WAXED_COPPER_CHEST:1
          - ACACIA_SIGN:1
          - ACACIA_FENCE:1
      Wall_Shelf_Mailbox:
        enabled: true
        kit-contents:
          - MANGROVE_SHELF:1
          - MANGROVE_SIGN:1
      Green_Shulker:
        enabled: false
        kit-contents:
          - GREEN_SHULKER_BOX:1
          - SPRUCE_SIGN:1
          - SPRUCE_FENCE:1
      Pink_Shulker:
        enabled: false
        kit-contents:
          - PINK_SHULKER_BOX:1
          - CHERRY_SIGN:1
          - CHERRY_FENCE:1
      Dropper:
        enabled: false
        kit-contents:
          - DROPPER:1
          - PALE_OAK_SIGN:1
          - PALE_OAK_FENCE:1
      Dispenser_Kit:
        enabled: false
        kit-contents:
          - DISPENSER:1
          - CHERRY_SIGN:1
          - CHERRY_FENCE:1
      Ender_Chest:
        enabled: false
        kit-contents:
          - ENDER_CHEST:1
          - WARPED_SIGN:1
          - WARPED_FENCE:1
      Chiseled_Bookshelf:
        enabled: false
        kit-contents:
          - CHISELED_BOOKSHELF:1
          - ACACIA_SIGN:1
          - ACACIA_FENCE:1
      Crafter:
        enabled: false
        kit-contents:
          - CRAFTER:1
          - BAMBOO_SIGN:1
          - BAMBOO_FENCE:1

kit-contents is a YAML list of strings. Write one MATERIAL:amount entry after each dash, with no space between the material and colon; CHEST:1 is a string, whereas CHEST: 1 becomes a YAML mapping and is not a kit item. Keep enabled and kit-contents beneath the named kit, not beneath mailbox.kit directly. Do not use item/template/XP package syntax for building kits.

mailbox:
  kit:
    notification-frequency-minutes: 30
    kits:
      Blue_Shulker:
        enabled: true
        kit-contents:
          - BLUE_SHULKER_BOX:1
          - OAK_SIGN:1
          - OAK_FENCE:1

Merge the custom kit into your existing mailbox.kit.kits map; do not replace other kits or create duplicate mailbox keys. /mb kit gives the only available kit immediately, otherwise lists available kits; /mb kit page 2 pages the list and /mb kit Blue_Shulker selects by name. Names are case-insensitive. usage counts claims across all kits, not once per kit; spare inventory space is recommended because leftover blocks drop at the player’s location. Reload with /mba reload and test with a player who has mailboxgui.player.kit and remaining uses.

Personal and Public Access floating new-mail items are owner-specific indicators, not collectible rewards or public unread-mail disclosures. config.yml controls their enablement/base material; gui.yml can style them without changing their position, privacy or lifecycle.

Public Access Mailboxes are communal access points: each visitor opens their own mail, never a shared chest of other players’ deliveries. They replace the old “Post Office / PO Box” wording. Personal registration, public registration and the Shared Admin Inbox are three different concepts.

1. Enable public-mailbox and its mailboxes subsection in config.yml. Build a supported public mailbox; classic public builds do not require the personal fence.
2. Open /mba tools and the Public Access Mailbox registration workflow. Select/register the location and assign its public name through the prompts.
3. Test with a non-admin account. If allow-any-player-open is false, grant mailboxgui.player.postoffice.pobox to intended users.
4. Use the registration overview to manage locations. Public mailbox unregister uses Shift-Right-Click; review the selection before confirming.
5. For an NPC access point, install Citizens and use the Public Access NPC registration workflow in Admin Tools. Grant mailboxgui.player.postoffice.npc where needed.

Sign templates use %publicmailboxname%; legacy %postofficename% values are migrated. Public registration lists, Dynmap wording and GUI lore use current terminology, while historical permission/API/SQL names may remain for compatibility. Verified Citizens NPC identities are excluded from ordinary player imports; real-player evidence takes precedence during backed-up cleanup.

A player inbox has four pages of 36 mail positions (144 active positions). Persistent overflow waits for space; it is already delivered mail and is different from a delayed-mail queue whose arrival deadline has not been reached. Use global page controls and Refresh where shown. Live views update after sends, claims, edits and deletions.

mailbox:
  mailbox-check-command:
    setting: gui
    paper-letter-readable: true
  mail-tracking:
    enabled: true

To use chat summaries set mailbox.mailbox-check-command.setting: text, not chat. paper-letter-readable affects only the GUI preview. Opening a real inbox marks its normal mail-notification state checked; /mb check is deliberately read-only and leaves that state intact.

A floating indicator, unchecked count, inbox occupancy and delayed count represent different states. Expired mail is excluded where documented; stored occupancy may still include it until cleanup. A package window is a revision-checked view, not a long-lived lock on the whole inbox. A stale click refreshes instead of claiming an item that moved.

Use a registered mailbox’s compose controls or /mb letter when player command sending is enabled. Paper and book types have independent enablement, player command/world rules, admin send rules, server sender names and delivery delays. Both default to enabled with a five-second delivery delay.

When only one player letter type is enabled, composition skips the type chooser; with both enabled, select paper or book first. The type-level enabled value controls player sending only, not administrator/API/scheduled mail or reading letters already received. There is no shared letter.enabled key in the 6.1.0 default.

• Paper letters use a text body displayed with translated mail information. Follow recipient/message prompts and review before sending.
• Book letters use a temporary writable book and title/sign workflow. Cancelling restores protected hotbar state; do not replace the plugin’s temporary-book lifecycle with unrelated book commands.
• The information page can show sender, date, title, expiration and controlled Reply/Back links. Eligible player-origin books can reply; admin-origin books do not create an arbitrary player reply target.
• Taking the finished book removes internal inbox navigation links. Reading closes the physical inbox; returning from the book does not silently reopen an old transactional inventory.

Colors, line breaks and body limits

Supported display styles include legacy & colors, compact &#4498DB and expanded HEX, and visual MiniMessage colors/decorations/gradients/rainbow/reset. Interactive click, hover, command and custom-font tags are not executed. Built-in book navigation is controlled by the plugin, not sender-written tags.

/mba sl Alex "&#4498DBWelcome!/n&fEnjoy your stay." --from "&6Server" --delay 0 --expire 7d
/mba sla Alex "Your town guide starts here." --title "Town Guide" --from "&6Mayor"

Use /n for a manual newline and //n for literal /n. Quote formatted YAML strings because an unquoted # starts a YAML comment. Sender-written messages survive stored delivery, delay, returns and reloads; editing a language template does not rewrite those payloads.

Packages use a 54-slot menu with 28 content positions: 10–16, 19–25, 28–34 and 37–43. Navigation and decoration are not payload slots. Claims retain unclaimed contents and validate the current mail revision. gui.yml only changes presentation, never real items or inventory dimensions.

• Player package composition is available from the mailbox when enabled; /mb package is disabled by default until package.player-command-send.enabled is true.
• Optional messages use the same formatting/line limits as paper letters. --message is supported for admin packages, COD and money mail; messages are kept after acceptance and returns.
• XP can be included as a checked reward. package.experience.enabled defaults true, max-experience-per-package -1 means no configured cap, and withdraw-from-sender-on-send defaults true for player sending.
• Loaded shulker sending is controlled by mailbox.loaded-shulker-box.enabled and defaults false. Enabling it does not bypass nested-content compatibility in Premium networking.
• Save a held custom item with /mba itemtemplate save event_sword. Use t:event_sword:1 in an admin package or schedule instead of assuming MATERIAL syntax can reproduce custom metadata.

/mba itemtemplate save event_sword
/mba sp Alex DIAMOND:3 EMERALD:5 xp:250 --message "&bEvent rewards!/n&fThank you." --delay 0
/mba sp Alex t:event_sword:1 --from "&6Event Team" --expire 3d

COD means cash on demand: the recipient previews the package and must accept its required payment before claiming protected contents. Prices can combine economy money and item/template/XP currency. Enable package.cash-on-demand and the chosen currency mechanisms; Vault plus an economy provider is required only for monetary components.

/mba scod Alex p:250 DIAMOND:3 --message "Auction purchase" --expire 2d
/mba scod Alex p:EMERALD:10 DIAMOND:3
/mba scod Alex p:250,EMERALD:10 r:admin DIAMOND_BLOCK:1 --message "Pay both price components"
/mba sm Alex 100 --message "Weekly reward" --from "&6Rewards" --delay 0

p:/price: supply the price; r:/return: supply the return destination. r:admin routes eligible returns/payments to the Shared Admin Inbox, not a player named “admin”. t:/template: refer to saved items and xp: to experience. Price/contents must be valid and fit the package capacity. Preview is not acceptance; item-currency payment and returned packages are distinct stored mail types.

send-reward-in-mail defaults true: player monetary COD rewards are delivered as money mail instead of directly through the provider. Return behavior also depends on the selected return destination/flow. Decline/expiration can return contents; a message stays attached to accepted or returned packages. Money mail withdraws/pays through the configured economy rather than being a decorative number.

package:
  cash-on-demand:
    enabled: true
    vault-economy-currency: true
    item-currency: true
    send-reward-in-mail: true
money:
  enabled: true
  display-format-mode: PROVIDER
  custom-format: "$%amount%"
  amount-format: "#,##0.00"

Players can choose online text notices, notification sound, simple/advanced/off login summaries and kit reminders independently. /mb settings and /mb settings help show the available notification, resource-pack and Discord categories, not a combined status dump. If only notifications are available, they open notification help directly. Non-Discord settings help uses the main MailboxGUI version header, localized descriptions and your command syntax.

/mb settings
/mb settings help
/mb settings notification
/mb settings notification help
/mb settings notification status
/mb settings notification offline advanced
/mb settings notification online on
/mb settings notification soundalert off
/mb settings notification kit on
/mb settings resourcepack help
/mb settings resourcepack auto

Kit preference availability requires enabled kits, enabled kit notifications and remaining uses. A notification-frequency-minutes value of 0 disables automatic reminders, but no longer hides the kit toggle, help, completion or notification status. Changing the personal toggle does not override that server interval. Exhausted/disabled kits do not expose the control.

Floating new-mail items are protected owner-specific visuals. config.yml controls personal/public notification enablement and original material; sounds.yml supplies sound settings. Disabling text/sound does not stop mail from arriving. Silent admin/API/scheduled deliveries still refresh normal inbox state.

Open /mba tools for the supported admin inventory workflows: compose mail, select individual/bulk audiences, inspect player inboxes, manage registrations/public access and use templates. Controls are permission-checked; a hidden/unavailable function is not enabled by changing its icon. Package composition keeps Send, XP, COD and Cancel click actions aligned with the displayed layout even when item-currency COD is available but Vault monetary COD is not; backend targeting and expiration do not shift those actions.

• Admin Check Player Inbox uses date ordering independently of the player’s chosen filter. It refreshes after player/admin changes while retaining the correct owner/session.
• Package management separates viewing/taking contents from Shift-Right-Click to Delete Package. Review the displayed action before deleting; sender attachments and current revisions remain protected.
• Shared Admin Inbox is available in BOTH editions. Open /mba admininbox or /mba ai. It can hold staff mail, COD item-currency payments, monetary payouts and declined/expired returns.
• Focused permissions govern staff opening, taking, deletion, money collection, clearing COD returns, clearing all and notifications. /mba inboxnotification on|off toggles your staff notices.
• The obsolete mailbox.admin-mailbox configuration block is not a required enablement switch. Do not add old keys to activate the current Shared Admin Inbox.

/mba tools
/mba admininbox
/mba inboxnotification on
/mba sl Alex,Sam "Server maintenance tonight" --from "&6Staff"
/mba sp onlineplayers DIAMOND:1 --message "Event prize"
/mba sm offlineplayers 25 --message "Welcome back reward"

Bulk audiences are allplayers, onlineplayers and offlineplayers; comma-separated recipients can combine known names and audience tokens. Selection resolves before mutation. admin-mail.include-sender-in-bulk-audiences controls whether the sending player is included. Do not confuse the visible sender label with mail origin or permission.

Canonical English roots are /mailbox or /mb for players and /mailboxadmin or /mba for admins. /mailbox admin exposes the admin route too. Commands below are typed by players with a slash; omit the slash in a server console. <angle brackets> are required values; [square brackets] are optional; | means choose one value. Do not type the brackets or a literal ellipsis.

DiscBridge-specific command entry points

The player category also honors the companion’s administrator-controlled setup gate and DiscordSRV readiness. Premium can forward integrated commands to a compatible companion on the DiscordSRV backend; changes persist on that host. A disabled/incompatible recovery-capable companion may retain authorized update-only administration without restoring normal Discord settings or notifications. The companion wiki explains its paged help, player guide and recovery limits.

Send flags and payload grammar

Common flags: --from "sender" (-f), --delay <seconds> (-d), --expire <duration>; book letters require --title "title" (-t). Packages, COD and money accept --message "body", including the supported equals form. Explicit sender/delay override the corresponding mail-type config. Duration examples: 30s, 10m, 2h, 2hr, 7d. Keep recipients CSV free of spaces and quote multiword text.

/mba sl Alex "A delayed letter" --delay 60 --expire 7d
/mba sp Alex,Sam DIAMOND:2 --message="Thank you"
/mba sla onlineplayers "Rules and welcome" --title "Welcome"
/mba sp Alex DIAMOND:1 --server survival
/mba sp Alex DIAMOND:1 --servers survival,lobby
/mba sl Alex "Event invitation" --exclude-servers creative
/mba sm Alex 50 --server-group gameplay

Testing commands and destructive actions

/mba testletter paper|book <player> <amount>
/mba testpackage standard|codv|codi|codvi|codip|codr|coda <amount> <player>
/mba testmoney standard|cod <player>
/mba testaipackage codr|codi <amount>
/mba testaimoney <amount>

Testing routes are administrative fixtures, not player economy shortcuts. Use only a controlled test environment. Purge first displays a preview; /mba purge <player|all> CONFIRM deletes inbox mail and all also includes the Shared Admin Inbox, but does not mean all registrations, delayed mail and schedules are reset. Clean is backed-up legacy-file cleanup: in game follow its chat-confirmation prompt; only console uses clean confirm. Keep a verified backup before either operation.

Hidden test routes require debug.enabled: true in addition to their focused test permission, the admin umbrella or operator access. This optional debug key is not present in the stock config; do not enable it on a public production server merely to send ordinary mail. Supported convenience aliases include /mba ai for admininbox and /mba it save|delete|list|give for itemtemplate; internal book navigation commands are generated by MailboxGUI and should not be typed manually.

Display language and executable command syntax are separate. locale.default / auto-detect-player-locale control messages, GUI and date/time presentation. locale.command-syntax.default / auto-detect-player-locale control help, structural aliases, flags and completion. File/config keys and permission nodes remain English.

These MailboxGUI locale settings also control DiscBridge’s local notices and integrated command language. DiscBridge no longer has duplicate locale/default-language settings. On the companion host, MailboxGUI locale.default supplies the Discord DM fallback and mass-mail channel language. A player’s saved Discord language overrides the DM fallback; Minecraft client language never chooses a Discord DM language, including while online.

locale:
  default: es
  auto-detect-player-locale: true
  command-syntax:
    default: es
    auto-detect-player-locale: false

1. Choose a supported locale and edit config.yml. Customize wording in language/messages_<locale>.yml rather than renaming executable keys.
2. Use /mba reload for display/template changes. Changing the default COMMAND root language requires your normal planned restart: roots are registered at startup, not replaced by reload.
3. At startup only English plus the chosen default language’s root set is registered. A default of en registers only English roots; it does not make every translated root available.
4. With command detection disabled, English roots show English syntax and the registered localized roots show their language. Console and unsupported client locales follow the invoked root.
5. With command detection enabled, supported client locales change subcommands/help/flags/completion, not which roots exist. English canonical syntax remains accepted; use it as the stable fallback.

Below, every language’s root, localized structures, accepted aliases, flags and argument labels come from the bundled executable dictionaries. Identifiers and values—player names, kit/template/backend IDs, permissions, credentials, codes and message content—are not translated. Structural tokens/audience aliases may have localized spellings; the English p:, r:, t:, xp: forms and English audience names remain usable. Internal book reply/back routes are plugin-managed rather than ordinary player commands.

/mb register
/mb settings resourcepack auto
/mba sl Alex "Welcome!/nEnjoy your stay." --from "Server" --delay 0
/mba sp Alex DIAMOND:1 --message "Your reward"
/mba sp Alex DIAMOND:1 --server survival

/pf registrieren
/pf einstellungen ressourcenpaket automatisch
/apf papierbriefsenden Alex "Welcome!/nEnjoy your stay." --absender "Server" --verzögerung 0
/apf paketsenden Alex DIAMOND:1 --nachricht "Your reward"
/apf paketsenden Alex DIAMOND:1 --server survival

/bz registrar
/bz ajustes paquetederecursos automático
/bza enviarcartapapel Alex "Welcome!/nEnjoy your stay." --remitente "Server" --demora 0
/bza enviarpaquete Alex DIAMOND:1 --mensaje "Your reward"
/bza enviarpaquete Alex DIAMOND:1 --servidor survival

/bal inscrire
/bal paramètres packderessources automatique
/bala envoyerlettrepapier Alex "Welcome!/nEnjoy your stay." --expéditeur "Server" --délai 0
/bala envoyercolis Alex DIAMOND:1 --message "Your reward"
/bala envoyercolis Alex DIAMOND:1 --serveur survival

/cp registra
/cp impostazioni pacchettorisorse automatico
/cpa invialetteracarta Alex "Welcome!/nEnjoy your stay." --mittente "Server" --ritardo 0
/cpa inviapacco Alex DIAMOND:1 --messaggio "Your reward"
/cpa inviapacco Alex DIAMOND:1 --server survival

/bb registreren
/bb instellingen resourcepakket automatisch
/bbb verstuurpapierbrief Alex "Welcome!/nEnjoy your stay." --afzender "Server" --vertraging 0
/bbb verstuurpakket Alex DIAMOND:1 --bericht "Your reward"
/bbb verstuurpakket Alex DIAMOND:1 --server survival

/bl registrera
/bl inställningar resurspaket automatiskt
/abl skickapappersbrev Alex "Welcome!/nEnjoy your stay." --avsändare "Server" --fördröjning 0
/abl skickapaket Alex DIAMOND:1 --meddelande "Your reward"
/abl skickapaket Alex DIAMOND:1 --server survival