!MailboxGUI-DiscBridge Banner

MailboxGUI-DiscBridge

DiscordSRV Notifications

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 letters, packages, COD packages, 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 requires MailboxGUI 5.0.0 or newer.

• MailboxGUI on Modrinth: /plugins/mailboxgui
• MailboxGUI on SpigotMC: https://www.spigotmc.org/resources/mailboxgui-advanced-mailboxes-packages-velocity-network-support.134394/
• DiscordSRV: Install and configure DiscordSRV before using DiscBridge.

---

Requirements

MailboxGUI-DiscBridge requires:

• MailboxGUI 5.0.0 or newer
• 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.

---

What DiscBridge Does

MailboxGUI-DiscBridge sends Discord notifications for MailboxGUI mail delivery.

Supported notification types:

• Player letters
• Player packages
• COD packages
• 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.

---

Release Highlights

MailboxGUI-DiscBridge 1.0.0 is 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.

---

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

---

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.

---

DiscordSRV Setup

Before using MailboxGUI-DiscBridge:

1. Install MailboxGUI.
2. Install DiscordSRV.
3. Configure DiscordSRV with your Discord bot token.
4. Invite the bot to your Discord server.
5. Confirm DiscordSRV starts successfully.
6. Install MailboxGUI-DiscBridge.
7. 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"

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 config.yml because they are server branding/customization messages.

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 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

---

Language Support

MailboxGUI-DiscBridge includes language files for in-game command messages.

Supported languages:

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

Discord DM and channel templates stay in config.yml because they are server branding/customization messages.

---

Upgrade Safety

DiscBridge 1.0.0 includes upgrade-safe synchronization for:

• config.yml
• language files
• player preference data

Existing custom values are preserved where possible.

The old beta default:

server-name: "ImagineCraft"

is replaced with the generic default:

server-name: "Minecraft Server"

when it was not customized.

---

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.

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

---

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