Richer Mail, Custom GUIs & Connected Networks

MailboxGUI Premium First Release

MailboxGUI Premium includes the shared mail-system improvements introduced in 6.1.0 and adds multi-backend networking, controlled backend targeting, mixed-version compatibility, and network administration tools.

Free/Premium Changes

Package And Money Messages

• Attach optional messages to standard packages, COD packages, and money mail through player composition, Admin Tools, supported commands, scheduled mail, and the API.
• Messages remain attached when COD packages are accepted or returned. Inbox lore displays a localized Message heading, with dividers separating mail information, the message, and click actions.
• Added --message "message" support, validation, help, and tab completion to applicable sending commands. Composition offers message/no-message choices; money composition can capture a message before requesting the amount.
• Expanded packages to 28 content slots, arranged as four rows of seven inside a six-row GUI. Player/admin composition, package management, commands, and API limits share this capacity. Removed the obsolete package.size-in-rows setting.

Colors And Letter Customization

• Added compact HEX colors such as &#4498DB and visual MiniMessage formatting, including gradients, decorations, rainbow, and reset. Existing legacy & colors and expanded HEX formatting remain supported.
• Configurable messages, sender names, GUI text, chat-captured mail, command messages, scheduled content, and API text share the formatting system. Sender formatting no longer bleeds into the rest of a new-mail notification.
• Added /n for manual line breaks and //n for a literal /n. Paper letters and package/COD/money messages support 256 visible characters, wrap at 28 visible characters, and allow up to 17 rendered body lines total, including automatic wrapping, blank lines, and manual breaks. Formatting codes do not consume visible-character space.
• Paper and book letters now have separate player sending, command sending, world restrictions, Admin Tools sending, admin-command sending, sender-name, and delivery-delay settings. Existing values migrate rather than resetting to new defaults.
• Disabling a letter type for players does not disable administrator, scheduled, or API sending, or access to existing letters. When only one player letter type is available, composition skips letter-type selection.
• Added a customizable, localized book information page with sender, date, title, optional expiration, dividers, and built-in Reply/Back controls. Original body pages are retained, and date formatting can follow the locale or a configured Java date pattern.
• Reading a book closes the physical mailbox; returning to the inbox keeps it closed until the next physical interaction. This also applies to Public Access Mailboxes.
• MiniMessage support is for visual formatting, not owner-defined click/hover actions or custom-font tags. Book navigation remains controlled by the plugin.

Custom GUIs And Resource Packs

• Added optional gui.yml customization for navigation, fillers, information controls, recipient icons, mail appearances, and personal/public floating new-mail notification items.
• Shared controls use consistent settings across their menus. Recipient online/offline icons remain separate. Packages and money mail support applicable message/no-message and expiration variants; paper/book letters use base and expiration appearances because letters inherently contain a message.
• Supports materials, CustomModelData, supported modern item models, tooltip styles, and optional ItemsAdder items through itemsadder-item: namespace:item. More-specific appearance variants inherit earlier values, and YAML null deliberately retains inherited/default values.
• ItemsAdder supplies custom item metadata while MailboxGUI retains its text, identity, and actions. Missing providers/items fall back safely; registry reloads refresh floating notifications and newly opened menus resolve current items.
• Added /mb settings resourcepack on|off|auto. on enables configured appearances for manually installed client packs, off uses built-in icons, and auto uses server-pack load confirmation. Automatic mode retains built-in icons while pack status is unknown, pending, declined, or failed.
• Added optional automatic-only detection and a provider-owned, expiring resource-pack status API for external pack providers. Successful pack confirmations refresh an already-open player inbox. MailboxGUI does not build, send, or force a resource pack, and cannot inspect individual assets or detect manually installed client packs.
• Floating notification appearance overrides affect item metadata, not the global notification enable settings, physical position, or lifecycle.
• gui.yml is generated only when customization is enabled. /mba reload generates or reloads it; disabled customization leaves an existing file intact and ignored. Detailed comments explain settings, inheritance, fallback, and compatibility.

Languages, Commands And Settings

• Added Brazilian Portuguese, bringing support to 16 locales: English, German, Spanish, French, Italian, Japanese, Korean, Dutch, Polish, Brazilian Portuguese, Russian, Swedish, Ukrainian, Simplified Chinese, Hong Kong Chinese, and Traditional Chinese.
• Expanded translations for GUI text, mail information, filters, click/Shift actions, notifications, help, guide/kit item names, errors, dates, times, and durations. Mail display text follows the viewer's locale rather than remaining fixed to the sending language.
• Added localized roots, subcommands, meaningful abbreviations, flags, argument labels, help, and tab completion while retaining English commands. Organized language files into matching categories with translated comments and refreshed visual formatting.
• Command syntax has separate locale controls. Startup registers English roots plus the configured default language's roots; an English default registers only English roots. Changing the root language requires a restart. Client-locale detection changes subcommands/help/completion, not registered roots.
• Player names, kit/template IDs, backend IDs, permissions, configuration keys, credentials, and message payloads are not translated as command syntax.
• Consolidated player sending under /mb send <letter|package|money>. Help lists only available sending types, respecting configuration, permissions, and world restrictions.
• Reorganized settings help and added /mb settings notification status. Resource-pack and Discord instructions remain within their settings sections; unavailable categories are hidden. Notification-only setups open notification help directly.
• Resource-pack settings show On/Off/Auto with descriptive help. Kit notification help/status/completion now reflects available uses and preferences correctly. Help styling follows MailboxGUI's version header and locale formatting.

Public Access And Inbox Management

• Renamed Post Office Mailboxes/NPCs to Public Access Mailboxes/NPCs across configuration, interfaces, messages, logs, and Dynmap integration. Existing registrations remain compatible.
• Migrates settings and %postofficename% formats to %publicmailboxname%, preserving customized values. Updated Dynmap categories/labels and removed obsolete public-mailbox renumbering settings.
• Public mailbox unregistering uses Shift-Right-Click; removing the final entry returns to registration instead of leaving a stale list.
• Added an administrator Shift-Right-Click package deletion action in player inbox management. Viewing/taking contents remains a separate action.
• Improved live inbox refreshes, package session tracking, fresh-state checks, and older-server mail recognition. Admin inbox checks retain their own date ordering; read-only /mb check remains read-only.

Delivery, Storage And Upgrade Safety

• Delayed mail uses absolute wall-clock delivery deadlines rather than tick-counted countdowns. Existing queued deadlines retain their remaining wait. Server-thread stalls or busy storage can still postpone execution.
• Scheduled packages and money mail support messages, formatting, manual line breaks, and explicit delivery-delay overrides. Tasks inherit the relevant sending delay unless overridden. Schedule reload does not trigger restart catch-up, and manual runs do not advance automatic occurrences.
• Invalid staged schedule/configuration reloads retain the active configuration. Scheduled examples document message fields and line limits, and command/API schedule edits preserve comments.
• Data version 7 upgrades supported older mail and packages while preserving contents and registrations. Portable outer-mail storage retains exact package bytes and rich book links; unreadable occupied records are not silently discarded.
• Improved custom-item metadata preservation for package composition, API sends, and item templates, including native item-byte support and custom codec hooks. Fixed phantom template entries caused by modern item serialization metadata. Unsupported/unreadable records remain protected rather than becoming empty packages.
• Fixed configuration reloads overwriting saved disk edits, improved runtime storage-setting refresh, and strengthened conversion/revision handling. Storage conversion validates copied totals before switching providers; it replaces a destination rather than merging into it, and is blocked while network mode is active.
• Added staged validation, installation snapshots, and safer shutdown handling. Missing/unloaded worlds do not justify deleting registrations. Recognized stock configuration/language values upgrade while custom values, comments, and extra language keys are preserved.
• Verified Citizens NPC identities are excluded from player imports and recipient discovery. Mistakenly imported NPC records receive guarded, backed-up cleanup; real-player evidence takes precedence, and legitimate Public Access NPC registrations remain intact.
• Expanded /mba clean and 30-day retention coverage for upgrade backups. Active data, migration markers, incomplete/temporary snapshots, and backups required by upgrade journals remain protected. Verify the upgrade before deleting rollback backups.

APIs, Placeholders, Updates And Compatibility

• Expanded the shared public API with capability reporting, immutable inbox queries, stable mail IDs/revisions, revision-aware mutations, lifecycle events, scheduling, registry snapshots, custom item codecs, notification providers, resource-pack confirmations, and formatting helpers. The shared API contract is version 2.0, distinct from the plugin release number.
• Added PlaceholderAPI values for unchecked mail, inbox types/value, capacity/overflow, pending delivery, expiration, registration limits, kits, and notification preferences. Existing placeholders remain supported; informational placeholders do not authorize claims.
• New shared placeholder names use %mailboxgui_<name>%: unchecked_total, has_unchecked_mail, unchecked_letters, unchecked_packages, unchecked_money, inbox_paper_letters, inbox_book_letters, inbox_packages, inbox_cod_packages, inbox_money, inbox_money_value, inbox_overflow, mail_total, inbox_capacity, inbox_free_slots, inbox_full, delivery_waiting, next_delivery_time, next_delivery_remaining, expiring_total, next_expiration_remaining, mailbox_limit, mailbox_remaining, kit_available, kit_uses_remaining, notifications_enabled, notification_sound_enabled, public_mailboxes, and public_npcs.
• DiscBridge commands integrate under /mb settings discord and /mba discord, with conditional help, setup gating, compatibility checks, and update-recovery support. The optional companion is not required to use MailboxGUI itself.
• Passive update checks and authorized admin notices remain configurable. /mba updatecheck reports newer release, beta, and alpha builds; /mba update follows updates.release-channel and explains when a different channel is needed.
• Updated compatibility handling for Spigot, Paper, and Purpur 1.18.2-1.21.11 and 26.1-26.3, with guarded API/model fallbacks. Plugin bytecode retains a Java 17 baseline; the server requires the Java version appropriate to its Minecraft release.
• Consolidated unsupported item-template warnings into one count. Install the final release JAR, not an original-* build artifact.

Premium Features

Shared Multi-Backend Mail

• Premium can begin in single-server mode for setup, then use its dedicated network/config.yml to enable multi-backend operation. Network mode requires shared MySQL/MariaDB storage and Redis; it is not SQLite/YAML networking.
• Share player inboxes, mail, registrations, public access, templates, and coordinated updates across participating backends. Live views reconcile after mail arrives, changes, or is claimed.
• Backend identities, display names, groups, presence, compatibility profiles, and runtime generations support routing and administration. Duplicate IDs and stale/conflicting runtime instances are guarded.
• Individual and mass-mail notifications reach the player's current backend, including notices for mail targeted elsewhere. Eligible admins receive network-wide Shared Admin Inbox notifications according to their preferences.
• Notification text/sound/offline/kit/admin preferences synchronize across backends. Resource-pack On/Off/Auto preferences are network-wide, while actual pack-loaded status remains local to the player's backend session.
• Sender names and default delays come from the sending backend. Explicit command/API overrides remain authoritative, and receiving backends do not recompute stored delivery deadlines.
• Remote unregistering refreshes other backends and clears the owning backend's sign, including guarded deferred handling for unloaded worlds/chunks. Missing or renamed backend IDs show unavailable/unloaded registrations.
• Optional shared kit coordination supports a designated sync.kit.main-backend, shared usage, and synchronized preferences.

Backend Targets And Mixed-Version Claims

• Send supported mail to one backend, multiple backends, configured groups, or targets with exclusions. Administrative targeting includes --server, --servers, --exclude-servers, and --server-group; Admin Tools offers backend/group selection after expiration.
• Targeted mail remains visible throughout the network, but reading or claiming requires an eligible target backend. Paper-letter bodies and book opening remain protected on ineligible backends.
• Mixed-version operation is optional through compatibility.multiversion-backends.enabled. Profiles validate version, data, serialization, protocol, and capability requirements; enabling it never permits unsupported items automatically.
• Compatibility checks cover individual entries and nested shulker/bundle contents. Fully supported, safely decoded items are not blocked solely because their source backend is newer. Unknown/corrupt payloads stay restricted instead of losing custom metadata.
• packages.allow-partial-unsupported-item-claims controls partial claiming. Disabled means incompatible packages remain restricted as a whole; enabled lets players take supported contents while preserving unsupported entries. Successful partial claims keep the package window open and refresh its state.
• Admin player-inbox and Shared Admin Inbox views can inspect contents independently of the player partial-claim toggle, but can take only eligible, supported items. Admin status does not bypass backend targets, COD acceptance, or compatibility checks.
• Restricted mail uses distinct configurable appearances while retaining expiration information. Restriction details identify target/group members, origin/local versions, blocked items, and known item-version or codec requirements.
• Restricted-backend letters, money, and package states offer a localized Shift-Right-Click deletion action. This discards the mail without payment, rewards, or COD return; ordinary usable backends retain their normal actions.
• New package XP rewards use a validated logical amount for cross-version claiming rather than a version-specific item payload. Existing unreadable item payloads are not guessed during recovery.

Coordinated Claims And Recovery

• Renewable distributed mutation locks, fresh reads, and revision checks protect simultaneous player/admin/backend operations. Merely viewing a package does not reserve a mutation lock for the whole window.
• COD processing checks compatibility before payment and coordinates stored acceptance, payout, and return records. Failed transactions reload authoritative data; uncertain external payouts are reported rather than blindly refunded.
• Durable delivery/occurrence receipts and post-commit refreshes strengthen delivery handling. The shared delayed queue uses bounded, earliest-due scans without letting repeatedly failing entries starve later eligible mail.
• Revision reconciliation, a durable event outbox, and bounded Redis stream replay help recover after disconnects. Fresh backends do not replay all historical arrival notices; damaged/full recovery records are preserved and reported.
• External Vault/inventory effects are not atomic with MySQL/Redis, and the event outbox is not atomic with the mail database. These safeguards are not a guarantee of exactly-once external effects or an unlimited notification archive; Redis replay also requires suitable persistence and retention.
• /mba reload reloads network settings and replaces relevant connections/workers, fencing stale callbacks. Degraded services stop unsafe coordinated actions rather than treating missing coordination as permission to proceed.

Network Scheduled Mail

• Configure execution scope (network.scope), execution owner (network.owner), recipient scope (recipients.scope), and claim target (delivery.target) separately. Backend-local jobs run independently; shared jobs coordinate one network occurrence.
• Shared schedules support a default owner and explicit ownership. An unavailable explicit owner waits safely instead of silently moving the task.
• Participating backends compare shared definitions, including payload, timezone, recipients, owner, targets, groups, notifications, and expiration. Conflicting definitions pause with diagnostics rather than sending different copies.
• Recipient selection uses current backend authority for online/permission evidence. Backend/group targets apply to supported scheduled mail types, including paper/book letters, packages, and money.
• Saved progression, deliveries, and receipts participate in JDBC transactions. Editing/reloading does not resend an already-completed automatic occurrence; manual runs remain separate. Scoped task history retains the latest 100 entries.
• Premium scheduling includes dedicated comments/examples and upgrade preparation. The plugin checks consistency but does not automatically copy scheduled task YAML between backends.

Network Tools And Custom Interfaces

• Network Tools is organized around Backends, Connections, Mail Delivery, Configuration Consistency, and Support Report.
• Backend/group screens show identity, membership, versions, capabilities, freshness, and local/remote status. Redis/MySQL screens show measured health, latency, timestamps, and sanitized reasons, distinguishing subscriber readiness from a successful ping.
• Mail Delivery provides delayed-routing views, delivery-ID/recipient-UUID search, result/details screens, and scheduled status/history. These diagnostics do not claim, delete, retarget, or resend mail.
• Configuration consistency compares common allowlisted settings without comparing credentials or backend-specific identity. Missing peer information remains pending, and remote configuration is not silently rewritten.
• Bounded local support reports exclude credentials, tokens, private message text, item payload bytes, and raw exception details. Focused permissions control diagnostics, delivery search, schedule status, consistency, and support exports.
• Premium GUI defaults include backend/group, connection, search, routing, scheduling, and restriction roles, with separate unsupported-item and unsupported-shulker appearances.
• With GUI customization enabled, gui.scope supports shared appearances by default or backend-local themes. Shared scope supports gui.shared-main-backend; a common pack can contain assets for different backend styles. Preference synchronization remains network-wide in either scope.

Network API And Placeholders

• The separate public mailboxgui-network-api exposes immutable cached backend/group/presence snapshots, routing eligibility, compatibility capabilities, freshness/generation data, notification metadata, and snapshot-change events.
• Companion coordination is bounded and revision-aware. APIs do not expose database/Redis credentials or bypass claim restrictions.
• New Premium placeholder names use %mailboxgui_<name>%: backend_id, backend_name, network_enabled, network_available, network_status, network_online, network_backends, network_stale_backends, network_stale_players, network_groups, and network_snapshot_age_ms.
• Dynamic placeholders include network_backend_<id>_status, network_group_<group>_members, network_group_<group>_online, and network_group_<group>_status, plus inbox_claimable, inbox_restricted, and inbox_restricted_<compatibility_status>. Cached diagnostic values do not guarantee a successful claim, inventory space, or sufficient COD funds.

DiscBridge Premium Integration

• Install DiscBridge 2.1.0 Premium on the DiscordSRV backend. Other MailboxGUI Premium backends discover that host and forward integrated player/admin commands through Redis, preserving permissions and language context.
• Discord preferences execute and persist on the companion host. Discovery, duplicate requests, unavailable/conflicting hosts, stale runtime generations, and timeouts receive guarded handling.
• /mba reload refreshes the detected local companion's network status without replacing a full DiscBridge reload. Use /mba discord reload for DiscBridge's own files/settings.
• Compatible recovery services keep approved update commands available for an incompatible/disabled companion, including Premium update-login setup, without enabling ordinary integration prematurely.
• Editions must match: MailboxGUI Premium requires DiscBridge Premium for Discord integration. Mixed editions are rejected with a clear warning; MailboxGUI itself remains usable without the optional companion.

Protected Updates And Purchase Linking

• Premium website downloads require an eligible purchased Premium license and website account credentials. The console-only update-login flow manages authentication; protect configuration/backups because the password is stored as plain text.
• Premium includes /mba spigotlink <account-link-code> and SpigotMC buyer/resource/download placeholders. Linking is optional for running a purchased plugin and requires all three injected identifiers; non-Spigot builds reject linking without contacting the website.
• Linking is product-specific: a MailboxGUI purchase does not grant a DiscBridge license. Requests are permission-gated, bounded, and rate-limited without logging private codes/download identifiers. Live linking depends on the website and buyer-verification service being enabled.

Installation And Upgrades

• Back up the complete plugin folder and selected database before replacing the JAR. File snapshots do not replace a MySQL dump or a consistent SQLite backup.
• Upgrading from MailboxGUI 6.0.0 or 6.1.0 Free preserves supported mail, registrations, templates, settings, and language customizations while adding Premium defaults. Keep existing files so migration can preserve customized values; do not delete configuration/language/data files as a normal upgrade step.
• Premium supports backed-up legacy network conversion for supported 5.0.0-5.1.1 installations, preserving storage/Redis settings, backend identities, registrations, and mail. Older compatibility paths remain retained.
• For a legacy shared-network upgrade, stop all old backends, back up the shared database and each plugin folder, migrate one Premium backend, verify it, and then start the remaining upgraded backends. Do not run old plugins concurrently against migrating shared data.
• Retain the correct storage type, database path/credentials, and backend IDs. Replacing configuration with defaults can select a different database and make existing data appear missing.
• Network setup requires reachable MySQL/MariaDB and Redis, unique backend IDs, and consistent shared policies. A Redis namespace does not separate mail stored in the same database; independent networks need separate databases and namespaces.
• Verify inbox/COD/delayed mail, public access, registrations, templates, scheduled tasks, and optional companion integration after upgrading. Retain rollback backups until those checks pass.