MailboxGUI-DiscBridge Banner

MailboxGUI-DiscBridge

DiscordSRV Notifications for MailboxGUI

MailboxGUI-DiscBridge is a standalone addon plugin for MailboxGUI that connects MailboxGUI mail delivery events to DiscordSRV.

Players can receive Discord notifications when mail is delivered in-game, including Classic Letters, Book Letters, packages, COD packages, COD item-currency payment mail, returned COD packages, money mail, admin/server mail, and API/system mail.

Required: MailboxGUI-DiscBridge is not a standalone mail plugin. It requires MailboxGUI and DiscordSRV to work.

Required Downloads

MailboxGUI-DiscBridge 1.1.1 requires MailboxGUI 5.1.0 or newer. MailboxGUI 5.1.1 or newer is recommended when using Vault2.0 custom currency support and the matching language updates.

MailboxGUI on Modrinth: https://modrinth.com/plugin/mailboxgui
MailboxGUI on SpigotMC: https://www.spigotmc.org/resources/mailboxgui-advanced-mailbox-package-letter-system-1-18-26-1.134394/
DiscordSRV: Install and configure DiscordSRV before using DiscBridge.

Requirements

MailboxGUI-DiscBridge requires:

MailboxGUI 5.1.0 or newer
MailboxGUI 5.1.1 or newer recommended for Vault2.0 custom currency support and matching language updates
DiscordSRV
Java 17 or newer
Paper / Spigot / Purpur backend server

MailboxGUI-DiscBridge runs on a backend server. It does not run on the Velocity proxy itself.

26.2.x Compatibility Note: MailboxGUI-DiscBridge 1.1.0 or newer is required for 26.2.x support because DiscBridge 1.1.0 requires MailboxGUI 5.1.0 or newer, and MailboxGUI 5.1.0 is required for Paper/Purpur 26.2.x compatibility. Use MailboxGUI-DiscBridge 1.1.1 or newer for the updated zh_cn and new zh_hk language files. Older DiscBridge versions do not support 26.2.x because they target older MailboxGUI versions and older notification payloads.

What DiscBridge Does

MailboxGUI-DiscBridge sends Discord notifications for MailboxGUI mail delivery.

Supported notification types:

Classic Letters
Book Letters
Packages
COD packages
COD item-currency payment mail
Returned COD packages
Money mail
Admin/server mail
API/system mail
Admin/API mass-mail channel notices

Individual mail can send Discord DMs when the recipient is eligible and has notifications enabled.

Admin/API mass mail sends one Discord channel notice by default so large server-wide mail does not spam every player with direct messages.

Optional queued mass-mail DMs are available for servers that want per-recipient Discord DMs for admin/API mass mail.

Release Highlights

MailboxGUI-DiscBridge 1.1.1 is the Chinese Language Update for the 1.1.x release line.

Highlights:

Updated Simplified Chinese (zh_cn) in-game command language file.
Updated Simplified Chinese (zh_cn) Discord DM/channel message template file.
Added new Hong Kong Traditional Chinese (zh_hk) in-game command language file.
Added new Hong Kong Traditional Chinese (zh_hk) Discord DM/channel message template file.
Added zh_hk support for /mbdiscord language <language>.
Added zh_hk support for language: "zh_hk" in config.yml.
Added zh_hk support for discord-messages.default-language: "zh_hk".
Updated language synchronization so old default zh_cn values can upgrade to the new bundled translation while preserving server-owner custom edits.
Updated Discord message synchronization so old default zh_cn Discord templates can upgrade safely while preserving server-owner custom edits.
Kept all 1.1.0 support for Book Letter notifications, COD item-currency payment notifications, MailboxGUI 5.1.x codPriceText, LOCAL mode, and NETWORK_NODE mode.

Previous 1.1.0 Highlights

MailboxGUI-DiscBridge 1.1.0 was the MailboxGUI 5.1.0 notification and Discord language update.

Highlights:

Added support for MailboxGUI 5.1.0.
Added support for Paper/Purpur 26.2.x through the MailboxGUI 5.1.0 release line.
Added Discord DM notifications for Book Letters.
Added Discord DM notifications for COD item-currency payment mail.
Updated COD package notifications so {price} can show MailboxGUI 5.1.x codPriceText.
Added localized Discord message files in /disclanguage/messages_*.yml.
Added translated Discord message templates for all supported languages.
Added player-selectable Discord DM languages with /mbdiscord language <language>.
Added direct upgrade migration from old 1.0.x config.yml messages.* into disclanguage/messages_en.yml.
Added migration support for old unreleased test-build root messages.yml, if present.
Updated /mbdiscord admin reload to reload config, Discord message language files, in-game language files, and player data.
Kept full LOCAL and NETWORK_NODE operating mode support.

Previous 1.0.0 Stable Highlights

MailboxGUI-DiscBridge 1.0.0 was the first stable release of the DiscordSRV notification bridge for MailboxGUI.

Highlights:

Added LOCAL and NETWORK_NODE operating modes.
Added support for MailboxGUI 5.0.0 network setups.
Added Discord DMs for eligible individual mail.
Added admin/API mass-mail channel notices.
Added optional queued mass-mail DMs with recipient caps.
Added duplicate event protection.
Added client-locale support for command messages.
Added paged /mbdiscord help.
Added /mbdiscord admin mode diagnostics.
Expanded /mbdiscord admin status diagnostics.
Added website-powered update checks and staged update commands.
Added config synchronization from 0.1.0-Beta to 1.0.0.
Added language file synchronization and final 1.0.0 language polish.

Compatibility

MailboxGUI-DiscBridge 1.1.1 follows the backend compatibility of MailboxGUI 5.1.x.

Supported server versions:

Spigot/Paper/Purpur 1.18.2 through 1.21.11
Spigot/Paper/Purpur 26.1.x
Spigot/Paper/Purpur 26.2.x

Required versions:

MailboxGUI-DiscBridge 1.1.1 requires MailboxGUI 5.1.0 or newer.
MailboxGUI 5.1.0 is required for Paper/Purpur 26.2.x compatibility.
MailboxGUI 5.1.1 or newer is recommended for Vault2.0 custom currency support and matching language updates.
Older DiscBridge versions do not support 26.2.x because they do not target the MailboxGUI 5.1.0 release line.
DiscordSRV is required.
Java 17 or newer is required.

Operating Modes

LOCAL Mode

LOCAL mode is the default mode for standalone or single-backend servers.

Use this mode when MailboxGUI, DiscordSRV, and MailboxGUI-DiscBridge are installed on the same backend server.

In LOCAL mode, DiscBridge listens to local MailboxGUI delivery events and sends Discord notifications through the local DiscordSRV instance.

NETWORK_NODE Mode

NETWORK_NODE mode is for MailboxGUI network setups.

Use this mode when MailboxGUI runs on multiple backend servers, but Discord notifications should be handled by only one backend.

In this setup:

MailboxGUI runs on every backend that uses mail.
MailboxGUI network mode must be enabled.
DiscordSRV and MailboxGUI-DiscBridge run on one backend only.
DiscBridge listens for MailboxGUI network notification events.
Other backend servers do not need DiscordSRV or DiscBridge.
DiscBridge does not run on the Velocity proxy itself.

This avoids copying the same DiscordSRV bot token and configuration across every backend.

For full network setup instructions, use the wiki:

https://plugins.imagine-craft.net/mailboxgui-discbridge/wiki/

Notification Rules

A Discord DM is sent only when:

Direct messages are enabled in config.
The recipient is linked through DiscordSRV.
The recipient has enabled notifications with /mbdiscord enable.
The recipient is offline, or online DMs are allowed.
The recipient has not ignored the sender.
The recipient has not ignored admin/server mail.

Online players do not receive Discord DMs by default because MailboxGUI already provides in-game notifications.

Players can allow online DMs with:

/mbdiscord online on

Individual Discord DMs use the recipient's selected Discord DM language when set. If the recipient has not selected a language, DMs use discord-messages.default-language from config.yml.

Discord Message Languages

DiscBridge 1.1.x stores Discord message templates in:

plugins/MailboxGUI-DiscBridge/disclanguage/

Supported files:

messages_en.yml
messages_de.yml
messages_es.yml
messages_fr.yml
messages_it.yml
messages_ja.yml
messages_ko.yml
messages_nl.yml
messages_pl.yml
messages_ru.yml
messages_sv.yml
messages_uk.yml
messages_zh_cn.yml
messages_zh_hk.yml
messages_zh_tw.yml

Players can choose their individual Discord DM language with:

/mbdiscord language <language>

Examples:

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

Player-selected Discord message languages only affect individual Discord DMs. They do not affect admin/API mass-mail channel notices.

Admin/API mass-mail channel notices always use the default language from config.yml:

discord-messages:
  default-language: "en"

Hong Kong Traditional Chinese can also be used:

language: "zh_hk"

discord-messages:
  default-language: "zh_hk"

Supported Chinese language codes:

zh_cn
zh_hk
zh_tw

Admin / API Mass Mail

Admin/API mail sent to multiple recipients sends one Discord channel notice by default.

Optional mass-mail DMs are available, but disabled by default. When enabled, DiscBridge checks actual DM eligibility before counting recipients and sends DMs through a queue to avoid sending too many Discord messages at once.

This makes it safer for large servers that use MailboxGUI admin mail, reward systems, quest rewards, vote rewards, shop rewards, or API-driven mail.

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

DiscordSRV Setup

Before using MailboxGUI-DiscBridge:

Install MailboxGUI 5.1.0 or newer.
Install DiscordSRV.
Configure DiscordSRV with your Discord bot token.
Invite the bot to your Discord server.
Confirm DiscordSRV starts successfully.
Install MailboxGUI-DiscBridge 1.1.1 or newer.
Link a player account through DiscordSRV.

Typical DiscordSRV link command:

/discord link

After linking, players can enable DiscBridge notifications with:

/mbdiscord enable

Configuration

Main config file:

plugins/MailboxGUI-DiscBridge/config.yml

Important settings:

mode: LOCAL

server-name: "Minecraft Server"

discord-messages:
  default-language: "en"

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

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

admin-mass-mail-direct-messages:
  enabled: false
  max-eligible-recipients: 10

updates:
  enabled: true
  channel: release

Discord DM and channel message templates are stored in:

plugins/MailboxGUI-DiscBridge/disclanguage/messages_*.yml

They are no longer stored in config.yml.

The old root file below is not used by the final 1.1.x system:

plugins/MailboxGUI-DiscBridge/messages.yml

Full configuration details are available on the wiki:

https://plugins.imagine-craft.net/mailboxgui-discbridge/wiki/

Commands

Player Commands

/mbdiscord help
/mbdiscord help 1
/mbdiscord help 2
/mbdiscord status
/mbdiscord enable
/mbdiscord disable
/mbdiscord online on
/mbdiscord online off
/mbdiscord online toggle
/mbdiscord language <language>
/mbdiscord ignore <player>
/mbdiscord unignore <player>
/mbdiscord ignorelist
/mbdiscord ignoreadmin
/mbdiscord unignoreadmin

Admin Commands

/mbdiscord admin status
/mbdiscord admin mode
/mbdiscord admin reload
/mbdiscord admin updatecheck
/mbdiscord update
/mbdiscord update confirm
/mbdiscord admin testdm <player>
/mbdiscord admin testchannel

Admin Diagnostics

/mbdiscord admin mode shows whether the bridge is running in LOCAL or NETWORK_NODE mode and explains the expected setup.

/mbdiscord admin status shows:

MailboxGUI hook status
DiscordSRV hook status
active mode
MailboxGUI network mode status
network notification node status
update channel
direct-message settings
mass-mail channel settings
mass-DM queue settings
duplicate protection state
notification counters

Update System

DiscBridge supports website-powered update checks and staged update downloads.

Useful commands:

/mbdiscord admin updatecheck
/mbdiscord update
/mbdiscord update confirm

The update command stages a newer valid MailboxGUI-DiscBridge jar for the next restart. It does not hot-swap the plugin while the server is running.

If a newer jar is already staged, the command tells admins to restart instead of downloading the same update again.

Permissions

mailboxguidiscbridge.use
mailboxguidiscbridge.online
mailboxguidiscbridge.ignore
mailboxguidiscbridge.ignoreadmin
mailboxguidiscbridge.admin
mailboxguidiscbridge.admin.reload
mailboxguidiscbridge.admin.status
mailboxguidiscbridge.admin.test
mailboxguidiscbridge.admin.update

The /mbdiscord language <language> command uses the normal player command access.

Language Support

MailboxGUI-DiscBridge includes language files for in-game command messages and separate Discord message language files.

Supported languages:

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

Supported Chinese language files:

messages_zh_cn.yml
messages_zh_hk.yml
messages_zh_tw.yml

Supported Discord message template files:

disclanguage/messages_zh_cn.yml
disclanguage/messages_zh_hk.yml
disclanguage/messages_zh_tw.yml

In-game command messages use:

plugins/MailboxGUI-DiscBridge/language/

Discord DM/channel templates use:

plugins/MailboxGUI-DiscBridge/disclanguage/

Upgrade Safety

DiscBridge 1.1.1 includes upgrade-safe synchronization for:

config.yml
in-game language files
Discord message language files
player preference data

Existing custom values are preserved where possible. Old default zh_cn values can upgrade to the new bundled translation, and missing zh_hk files are generated automatically.

For 1.0.x upgrades, old custom Discord messages from:

config.yml
messages:

are moved into:

plugins/MailboxGUI-DiscBridge/disclanguage/messages_en.yml

The old root messages.yml file is not used by the final 1.1.x system. If one exists from an unreleased test build, it is migrated into messages_en.yml, backed up, and removed.

Troubleshooting

Real Mail Notifications

Check:

Whether DiscBridge is in LOCAL or NETWORK_NODE mode.
Whether the recipient is linked with DiscordSRV.
/mbdiscord status
Online DM settings if the player is online.
Ignored players and ignoreadmin settings.
In NETWORK_NODE mode, confirm MailboxGUI network mode and Redis are working.

Book Letter Notifications

Check:

MailboxGUI is 5.1.0 or newer.
MailboxGUI-DiscBridge is 1.1.0 or newer. Use 1.1.1 or newer for zh_hk and the updated zh_cn files.
The selected/default file in disclanguage contains messages.dm-book-letter.
The recipient is linked and has enabled notifications.

COD Item-Currency Price Text

Check:

MailboxGUI is 5.1.0 or newer.
MailboxGUI-DiscBridge is 1.1.0 or newer. Use 1.1.1 or newer for zh_hk and the updated zh_cn files.
The selected/default Discord message file uses {price}.
MailboxGUI is sending codPriceText in the delivery payload.

Discord DM Language

Check:

The player ran /mbdiscord language <language>.
/mbdiscord status shows the selected language.
The matching file exists in disclanguage.
The notification being tested is an individual DM, not a channel notice.

Mass-Mail Channel Language

Mass-mail channel notices do not use player-selected languages.

Set the channel notice language with:

discord-messages:
  default-language: "en"

NETWORK_NODE Startup

Check:

MailboxGUI network mode is enabled on that backend.
DiscordSRV is installed on the DiscBridge backend.
Only the notification backend is running DiscBridge.

Mass-Mail DMs

This is normal by default. Mass mail posts one channel notice unless optional mass-mail DMs are enabled.

Online DMs

Online DMs are disabled by default. The player can run:

/mbdiscord online on

Contributors

Special thanks to project supporter and contributor nice for providing the updated Simplified Chinese (zh_cn) language files and the new Hong Kong Traditional Chinese (zh_hk) language files for MailboxGUI-DiscBridge 1.1.1.

This contribution includes:

language/messages_zh_cn.yml
language/messages_zh_hk.yml
disclanguage/messages_zh_cn.yml
disclanguage/messages_zh_hk.yml

Support

DiscBridge Wiki:
https://plugins.imagine-craft.net/mailboxgui-discbridge/wiki/

MailboxGUI Wiki:
https://plugins.imagine-craft.net/mailboxgui/wiki/

Discord Support Server:
https://discord.gg/kggbGwRt42

GitHub:
https://github.com/Rismr1/MailboxGUI-DiscBridge

MailboxGUI-DiscBridge

📖About MailboxGUI-DiscBridge

MailboxGUI-DiscBridge

DiscordSRV Notifications for MailboxGUI

Required Downloads

Requirements

What DiscBridge Does

Release Highlights

Previous 1.1.0 Highlights

Previous 1.0.0 Stable Highlights

Compatibility

Operating Modes

LOCAL Mode

NETWORK_NODE Mode

Notification Rules

Discord Message Languages

Admin / API Mass Mail

DiscordSRV Setup

Configuration

Commands

Player Commands

Admin Commands

Admin Diagnostics

Update System

Permissions

Language Support

Upgrade Safety

Troubleshooting

Real Mail Notifications

Book Letter Notifications

COD Item-Currency Price Text

Discord DM Language

Mass-Mail Channel Language

NETWORK_NODE Startup

Mass-Mail DMs

Online DMs

Contributors

Support