MailboxGUI-DiscBridge Wiki

What's New in 2.0.0

• Separate Free and Premium builds with strict edition pairing against MailboxGUI 6.0.0.
• Automatic LOCAL mode for Free and Premium NETWORK_NODE mode for network notifications.
• Mail expiration details are available to localized Discord notifications through the {expiration} placeholder.
• Separate Free and Premium update feeds, including protected Premium downloads.
• Premium update-login admin commands for saving, checking, or clearing website credentials.
• Configuration format updated to version 4.

What's New in 1.1.1

• Updated Simplified Chinese in-game language file: language/messages_zh_cn.yml.
• Added Hong Kong Traditional Chinese in-game language file: language/messages_zh_hk.yml.
• Updated Simplified Chinese Discord message template file: disclanguage/messages_zh_cn.yml.
• Added Hong Kong Traditional Chinese Discord message template file: disclanguage/messages_zh_hk.yml.
• Added zh_hk language selection, config language, and default Discord message language support.
• Special thanks to nice for contributing language/messages_zh_cn.yml, language/messages_zh_hk.yml, disclanguage/messages_zh_cn.yml, and disclanguage/messages_zh_hk.yml.

What's New in 1.1.0

• Book Letter Discord DM notifications for MailboxGUI 5.1.0 Book Letter deliveries.
• COD item-currency payment Discord DM notifications.
• Updated COD package {price} placeholder support using MailboxGUI 5.1.0 codPriceText.
• Localized Discord DM and channel message files under /plugins/MailboxGUI-DiscBridge/disclanguage/.
• New /mbdiscord language <language> command for each player's individual Discord DM language.
• Direct migration from 1.0.x custom config.yml messages.* templates into disclanguage/messages_en.yml.
• Migration support for the temporary unreleased root messages.yml test-build layout.

LOCAL Mode — Free

DiscBridge 2.0.0 Free automatically uses LOCAL. Use it for standalone servers and single-backend setups. Install MailboxGUI, DiscordSRV, and MailboxGUI-DiscBridge on the same backend. DiscBridge listens to local MailboxGUI delivery events and does not subscribe to MailboxGUI network Redis events.

DiscBridge Free must be paired with MailboxGUI Free.

NETWORK_NODE Mode — Premium

NETWORK_NODE belongs to the paid Premium edition, which is still in development and not released yet. It is designed for Velocity-style or BungeeCord-style networks using MailboxGUI Premium network mode. Install MailboxGUI on every backend that uses mail, enable MailboxGUI network mode on those backends, then install DiscordSRV and MailboxGUI-DiscBridge on only one backend.

DiscBridge Premium automatically uses NETWORK_NODE and must pair with MailboxGUI Premium. That backend acts as the Discord notification node. Other backends do not need DiscordSRV or DiscBridge unless you intentionally run separate notification systems.

DiscBridge does not run on the proxy itself. It reads Redis and network settings from MailboxGUI; DiscBridge has no Redis or MySQL config of its own. If NETWORK_NODE is selected but MailboxGUI network mode is disabled, DiscBridge disables safely with clear console errors.

Which Mode Should I Use?

• Use DiscBridge Free with MailboxGUI Free for a standalone backend; it automatically uses LOCAL.
• Use DiscBridge Premium with MailboxGUI Premium for a network notification node when Premium becomes available.
• Do not attempt to select a mode in config.yml; the edition controls it.
• Do not install DiscBridge on the proxy. Install it on a backend server.

Default config.yml

config-version: 4
locale:
  use-client-locale: true
  default-language: "en"

discord-messages:
  default-language: "en"

server-name: "Minecraft Server"

direct-messages:
  enabled: true
  send-to-online-players-by-default: false

duplicate-protection:
  enabled: true
  remember-event-ids-minutes: 30

admin-mass-mail-channel:
  enabled: true
  channel-id: ""
  mention-everyone: false

admin-mass-mail-direct-messages:
  enabled: false
  max-eligible-recipients: 10
  over-limit-behavior: channel_only
  queue:
    enabled: true
    delay-between-dms-seconds: 3
    max-retries: 1
    retry-delay-seconds: 30

updates:
  enabled: true
  channel: release
  check-on-startup: true
  notify-admins-on-join: true
  notify-permission: "mailboxguidiscbridge.admin"

  # Premium only: credentials used for protected Premium updates.
  auth:
    username: ""
    password: ""

Important Config Notes

• config-version for MailboxGUI-DiscBridge 2.0.0 is 4.
• There is no mode setting in 2.0.0. Free selects LOCAL; Premium selects NETWORK_NODE.
• The updates.auth section is Premium-only and stores credentials for protected Premium update downloads.
• locale controls in-game /mbdiscord command messages and fallback language.
• discord-messages.default-language controls fallback Discord DM templates and all admin/API mass-mail channel notices.
• locale.default-language: "zh_hk" is supported.
• discord-messages.default-language: "zh_hk" is supported.
• Player-selected Discord DM language only affects individual DMs and does not affect mass-mail channel notices.
• Default server-name is Minecraft Server.
• Online player DMs are disabled by default.
• Admin mass-mail DMs are disabled by default.
• Admin mass mail channel notice is one channel post.
• Update URLs are built into the plugin and are not exposed in config.

Discord Message Default Language

locale:
  default-language: "zh_hk"

discord-messages:
  default-language: "en"

locale.default-language controls fallback in-game /mbdiscord command messages. discord-messages.default-language is the fallback Discord message language. It is used when a player has not selected a Discord DM language, and it is always used for admin/API mass-mail channel notices. Player-selected Discord languages do not affect channel notices.

Hong Kong Traditional Chinese Discord default

discord-messages:
  default-language: "zh_hk"

Supported Chinese language codes are zh_cn, zh_hk, and zh_tw. Supported native names include 简体中文, 繁體中文（香港）, and 繁體中文.

Discord DM and channel templates are no longer stored in config.yml. Edit /plugins/MailboxGUI-DiscBridge/disclanguage/messages_*.yml instead.

Standalone Setup

1. Install MailboxGUI 6.0.0 Free.
2. Install DiscordSRV.
3. Install MailboxGUI-DiscBridge 2.0.0 Free. It selects LOCAL automatically.
4. Configure DiscordSRV.
5. Link account with /discord link.
6. Enable notifications with /mbdiscord enable.
7. Test with /mbdiscord admin testdm <player> and /mbdiscord admin testchannel.

Velocity/BungeeCord-Style Network Setup

This setup requires MailboxGUI Premium + DiscBridge Premium. Premium is paid, still in development, and not released yet.

1. Install MailboxGUI Premium on every backend that uses mail.
2. Enable MailboxGUI network mode on every backend.
3. Set up shared MySQL/MariaDB and Redis in MailboxGUI. Redis is required for network server mode.
4. Install DiscordSRV and DiscBridge Premium on only one backend; it selects NETWORK_NODE automatically.
5. Do not install DiscBridge or DiscordSRV on other backends unless intentionally running separate notification systems.
6. Use /mbdiscord admin mode and /mbdiscord admin status to confirm the node is active.
7. Send test mail from another backend and confirm the NETWORK_NODE backend sends the Discord notification.

Individual Mail

Player Classic Letter, Book Letter, package, COD package, COD item-currency payment, returned COD, and money mail can send Discord DMs when eligible. Admin single-recipient mail and API/system single-recipient mail can also send Discord DMs.

Discord DM Language Selection

Individual Discord DMs use the recipient's selected Discord DM language if one is set. Otherwise, DiscBridge uses discord-messages.default-language.

/mbdiscord language English
/mbdiscord language Spanish
/mbdiscord language Español
/mbdiscord language German
/mbdiscord language Deutsch
/mbdiscord language zh_cn
/mbdiscord language zh_hk
/mbdiscord language zh_tw

Supported codes: en, de, es, fr, it, ja, ko, nl, pl, ru, sv, uk, zh_cn, zh_hk, zh_tw.

Supported names include: English, Deutsch, Español, Français, Italiano, 日本語, 한국어, Nederlands, Polski, Русский, Svenska, Українська, 简体中文, 繁體中文（香港）, 繁體中文.

This command changes only that player's individual Discord DM language. It does not change admin/API mass-mail channel notice language.

DM Eligibility

• direct-messages.enabled must be true.
• The recipient must be linked with DiscordSRV.
• The recipient must have /mbdiscord enable.
• If the player is online, online DMs must be allowed globally or by player setting.
• The recipient must not ignore the sender.
• The recipient must not ignore admin/server mail for admin-like mail.

Admin/API Mass Mail

Default behavior is one Discord channel notice only. DiscBridge does not DM every recipient by default. Optional mass DMs are disabled by default.

If mass DMs are enabled, DiscBridge checks actual eligible recipients, counts only eligible recipients, honors the configured cap and queue settings, and can skip mass DMs while relying on the channel notice if the eligible count is over the cap.

Admin/API mass-mail channel notices always use discord-messages.default-language. Player-selected Discord DM languages do not affect channel notices. If optional queued mass DMs are enabled, those queued individual DMs use each recipient's selected Discord DM language when set.

Message Templates and Placeholders

Discord DM and channel templates live in /plugins/MailboxGUI-DiscBridge/disclanguage/messages_*.yml.

dm-book-letter:
  - "📬 You received a book letter from {sender} on {server}."
  - "Check your mailbox, a public Post Office box, or a Post Office NPC in-game."

dm-cod-package:
  - "📦 You received a COD package from {sender} on {server}."
  - "Price: {price}"
  - "Check your mailbox, a public Post Office box, or a Post Office NPC in-game."

dm-cod-item-currency-payment:
  - "💜 You received a COD item-currency payment from {sender} on {server}."
  - "Payment: {price}"
  - "Check your mailbox, a public Post Office box, or a Post Office NPC in-game."

Supported placeholders:

{server}
{sender}
{recipient}
{price}
{amount}
{expiration}
{mention}
{recipient_count}

In 2.0.0, {expiration} shows the expiration date and time for expiring mail and is blank when the delivery does not expire. The alias %expiration% is also replaced. The {price} placeholder supports MailboxGUI 6.0.0 codPriceText, including Vault money, item currency, XP, saved item/template currency, and combined COD prices.

Discord DM Language Command

/mbdiscord language <language> changes only the player's individual Discord DM language.

/mbdiscord language English
/mbdiscord language Spanish
/mbdiscord language Español
/mbdiscord language German
/mbdiscord language Deutsch
/mbdiscord language zh_cn
/mbdiscord language zh_hk
/mbdiscord language zh_tw

Supported codes: en, de, es, fr, it, ja, ko, nl, pl, ru, sv, uk, zh_cn, zh_hk, zh_tw.

Supported Chinese language codes are zh_cn, zh_hk, and zh_tw.

Test DM Works, Real Mail Does Not

• Run /mbdiscord admin mode; Free should report LOCAL and Premium should report NETWORK_NODE.
• Confirm MailboxGUI 6.0.0 and DiscBridge 2.0.0 use matching editions.
• In Premium NETWORK_NODE, make sure MailboxGUI Premium network mode and the Redis subscriber are active.
• Check that the recipient has run /mbdiscord enable.
• Check recipient online DMs if the recipient is online.
• Check DiscordSRV linking.
• Check /mbdiscord ignoreadmin and ignored player settings.

Book Letter Notifications Not Sending

• Use MailboxGUI 6.0.0 with DiscBridge 2.0.0 in matching editions.
• Confirm disclanguage/messages_en.yml or the selected language file contains messages.dm-book-letter.
• Confirm the recipient is linked through DiscordSRV and has enabled DiscBridge notifications.
• Check /plugins/MailboxGUI-DiscBridge/disclanguage/messages_*.yml, not a root messages.yml.

Discord DM Language Not Changing

• Make sure the player ran /mbdiscord language <language>.
• Use a supported code or name: en, de, es, fr, it, ja, ko, nl, pl, ru, sv, uk, zh_cn, zh_hk, zh_tw.
• Check /mbdiscord status for the selected Discord message language.
• Confirm the matching file exists under /plugins/MailboxGUI-DiscBridge/disclanguage/.
• Test an individual DM. Player-selected languages do not affect channel notices.

Mass-Mail Channel Language Not Changing

Mass-mail channel notices always use discord-messages.default-language. Player-selected Discord DM languages do not affect channel notices.

discord-messages:
  default-language: "en"

Edit the matching /plugins/MailboxGUI-DiscBridge/disclanguage/messages_*.yml file, then run /mbdiscord admin reload. Do not edit a root messages.yml; it is not the final active message file.

COD Item-Currency Price Blank or Incomplete

• Use MailboxGUI 6.0.0 with DiscBridge 2.0.0 in matching editions.
• Confirm the selected/default Discord message language file uses {price} in dm-cod-package and dm-cod-item-currency-payment.
• Check /plugins/MailboxGUI-DiscBridge/disclanguage/messages_*.yml, not a root messages.yml.

NETWORK_NODE Disables on Startup

• Confirm both MailboxGUI and DiscBridge are Premium editions; Free/Premium mismatches disable DiscBridge.
• MailboxGUI network mode is not enabled on that backend.
• DiscordSRV is missing on the DiscBridge backend.

NETWORK_NODE Does Not Notify

• Premium network functionality is not available in the Free editions.
• Run /mbdiscord admin mode and confirm Mode: NETWORK_NODE.
• Confirm the MailboxGUI hook, DiscordSRV hook, and MailboxGUI network mode are active.
• Install DiscBridge and DiscordSRV on only one backend that should act as the notification node.
• Check console for the NETWORK_NODE subscriber startup message.
• Send real mail from another backend and verify the one DiscBridge backend receives the network delivery payload.

No Mass Mail DMs

This is normal by default. DiscBridge sends a channel notice only unless admin-mass-mail-direct-messages.enabled is set to true.

Online Player Not Receiving DM

Default behavior disables online DMs. The player can run /mbdiscord online on, or the server can allow online DMs globally.

Update Staged but Not Applied

Restart is required. The update command stages the jar for next restart and does not update the running plugin immediately.

Multiple NETWORK_NODE Backends

Only one NETWORK_NODE backend is recommended. Duplicate event protection exists, but it is not intended as multi-node clustering.

Testing Checklist

Run these commands after installation or upgrade:

/mbdiscord admin status
/mbdiscord admin mode
/mbdiscord admin reload
/mbdiscord admin testdm <player>
/mbdiscord admin testchannel
/mbdiscord language
/mbdiscord language Spanish
/mbdiscord language Español
/mbdiscord language zh_cn
/mbdiscord language zh_hk
/mbdiscord language zh_tw
/mbdiscord status

Test these deliveries:

Classic Letter DM
Book Letter DM
Package DM
COD package with Vault money
COD package with item currency
COD item-currency payment mail
Returned COD package
Money mail
Admin one-recipient mail
Admin/API mass-mail channel notice
Optional queued mass-mail DMs if enabled