MailboxGUI-DiscBridge Wiki

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

LOCAL is the default mode. 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.

NETWORK_NODE Mode

NETWORK_NODE is for Velocity-style or BungeeCord-style networks using MailboxGUI 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.

Set DiscBridge mode: NETWORK_NODE on that one backend. 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 LOCAL for one Minecraft backend.
• Use LOCAL if DiscordSRV and MailboxGUI run on the same standalone server.
• Use NETWORK_NODE for a MailboxGUI network where one backend should send all Discord notifications.
• Do not install DiscBridge on the proxy. Install it on a backend server.

Default config.yml

config-version: 3
mode: LOCAL
language: "en"

locale-detection:
  use-client-locale: true
  fallback-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"

Important Config Notes

• config-version for MailboxGUI-DiscBridge 1.1.0 and 1.1.1 is 3.
• mode defaults to LOCAL.
• Valid modes are LOCAL and NETWORK_NODE.
• language 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.
• language: "zh_hk" is supported in 1.1.1.
• discord-messages.default-language: "zh_hk" is supported in 1.1.1.
• 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

language: "zh_hk"

discord-messages:
  default-language: "en"

language controls 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.
2. Install DiscordSRV.
3. Install MailboxGUI-DiscBridge.
4. Set mode: LOCAL.
5. Configure DiscordSRV.
6. Link account with /discord link.
7. Enable notifications with /mbdiscord enable.
8. Test with /mbdiscord admin testdm <player> and /mbdiscord admin testchannel.

Velocity/BungeeCord-Style Network Setup

1. Install MailboxGUI 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 MailboxGUI-DiscBridge on only one backend.
5. Set DiscBridge mode: NETWORK_NODE on that backend.
6. Do not install DiscBridge or DiscordSRV on other backends unless intentionally running separate notification systems.
7. Use /mbdiscord admin mode and /mbdiscord admin status to confirm the node is active.
8. 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}
{mention}
{recipient_count}

The {price} placeholder supports MailboxGUI 5.1.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

• Check mode: LOCAL vs NETWORK_NODE.
• In NETWORK_NODE, make sure MailboxGUI network mode is enabled and the Redis subscriber is active.
• Check that MailboxGUI is 5.1.0 or newer and DiscBridge is 1.1.0 or newer. DiscBridge 1.1.1 or newer is recommended for the updated zh_cn and new zh_hk language files.
• 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 5.1.0 or newer.
• Use MailboxGUI-DiscBridge 1.1.0 or newer for Book Letter notification support.
• 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 5.1.0 or newer so delivery events include codPriceText.
• Use MailboxGUI-DiscBridge 1.1.0 or newer for COD price text support.
• 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

• MailboxGUI network mode is not enabled on that backend.
• DiscordSRV is missing on the DiscBridge backend.

NETWORK_NODE Does Not Notify

• 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