MailboxGUI-DiscBridge Wiki

Getting Started

Wiki Version: 1.0.0

This wiki is written for MailboxGUI-DiscBridge 1.0.0. DiscBridge is a standalone addon plugin for MailboxGUI. It is not bundled into MailboxGUI, and it is not a Velocity proxy plugin.

DiscBridge runs on Spigot, Paper, or Purpur backend servers. It listens for MailboxGUI mail delivery events and sends Discord notifications through a local DiscordSRV instance.

Use mode: LOCAL for normal standalone servers. Use mode: NETWORK_NODE on exactly one backend when MailboxGUI network mode is enabled across a Velocity-style or BungeeCord-style server network.

Requirements

MailboxGUI 5.0.0 or newer.
DiscordSRV installed on the backend where DiscBridge runs.
Java 17 or newer.
Spigot, Paper, or Purpur backend server.
Minecraft compatibility matching MailboxGUI's supported range.
Redis is required for network server mode, but not for normal single-server installs.

Players must link their Minecraft account with DiscordSRV before DiscBridge can send them Discord DMs.

Download Links

Plugin	SpigotMC	Modrinth
MailboxGUI-DiscBridge	Coming soon	Coming soon
MailboxGUI	SpigotMC MailboxGUI	Modrinth MailboxGUI

Install MailboxGUI first. DiscBridge will not run without MailboxGUI.

Installation

Stop the backend server.
Install MailboxGUI 5.0.0 or newer.
Install DiscordSRV on the backend where DiscBridge will run.
Place the MailboxGUI-DiscBridge jar in the server plugins folder.
Start the server once to generate config, language, and data files.
Configure /plugins/MailboxGUI-DiscBridge/config.yml.
Restart the server or use /mbdiscord admin reload for safe config and language reloads.

plugins/
└── MailboxGUI-DiscBridge/
    ├── config.yml
    ├── language/
    │   ├── messages_en.yml
    │   └── ...
    ├── data/
    └── backups/

Operating Modes

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.

MailboxGUI-DiscBridge NETWORK_NODE mode diagnostic output — NETWORK_NODE diagnostic showing DiscBridge running as the single Discord notification node for a MailboxGUI network.

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.

DiscordSRV Setup

DiscBridge uses DiscordSRV for account linking and Discord delivery. Configure DiscordSRV first, confirm the bot is online, and have players link with /discord link.

The bot must be able to send direct messages for player DMs. If using the admin mass mail channel notice, the bot also needs access to the configured channel and permission to send messages there.

Configuration

Default config.yml

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

locale-detection:
  use-client-locale: true
  fallback-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.0.0 is 2.
mode defaults to LOCAL.
Valid modes are LOCAL and NETWORK_NODE.
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.

Message Templates

Discord DM and channel templates stay in config.yml because they are server branding and customization. In-game command messages use language files.

Network Setup with MailboxGUI

Standalone Setup

Install MailboxGUI.
Install DiscordSRV.
Install MailboxGUI-DiscBridge.
Set mode: LOCAL.
Configure DiscordSRV.
Link account with /discord link.
Enable notifications with /mbdiscord enable.
Test with /mbdiscord admin testdm <player> and /mbdiscord admin testchannel.

Velocity/BungeeCord-Style Network Setup

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

MailboxGUI-DiscBridge admin status output in NETWORK_NODE mode — Admin status output showing NETWORK_NODE, MailboxGUI network mode, duplicate protection, update channel, and notification counters.

Notification Behavior

Individual Mail

Player letter, package, COD, 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.

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.

Player Commands

Command	Purpose
`/mbdiscord help`	Shows the default player help page.
`/mbdiscord help 1`	Shows player help page 1.
`/mbdiscord help 2`	Shows player help page 2.
`/mbdiscord status`	Shows personal notification, online DM, ignore, and link status.
`/mbdiscord enable`	Enables personal Discord mail notifications.
`/mbdiscord disable`	Disables personal Discord mail notifications.
`/mbdiscord online on`	Allows Discord DMs while the player is online.
`/mbdiscord online off`	Disables Discord DMs while the player is online unless the server default allows them.
`/mbdiscord online toggle`	Toggles the player online DM preference.
`/mbdiscord ignore <player>`	Ignores player-origin mail notifications from a sender.
`/mbdiscord unignore <player>`	Removes a sender from the ignore list.
`/mbdiscord ignorelist`	Shows ignored player senders.
`/mbdiscord ignoreadmin`	Ignores admin/server mail notifications.
`/mbdiscord unignoreadmin`	Allows admin/server mail notifications again.

MailboxGUI-DiscBridge player command help page — Player command help page showing status, notification toggles, online DM controls, and ignore options.

MailboxGUI-DiscBridge player status command output — Player status output showing notification preferences, online DM state, and ignore settings.

Admin Commands

Command	Purpose
`/mbdiscord admin status`	Shows hook status, operating mode, MailboxGUI network mode, update channel, duplicate protection, mass DM queue, preferences, and notification stats.
`/mbdiscord admin mode`	Shows LOCAL or NETWORK_NODE diagnostics and whether the selected mode is usable.
`/mbdiscord admin reload`	Reloads config, language files, and player data.
`/mbdiscord admin updatecheck`	Checks the website release system for current/latest/type/summary details.
`/mbdiscord update`	Prepares an available update for staging.
`/mbdiscord update confirm`	Downloads and stages a newer valid MailboxGUI-DiscBridge jar for the next restart.
`/mbdiscord admin testdm <player>`	Sends a diagnostic direct-message test to a linked player.
`/mbdiscord admin testchannel`	Sends a diagnostic message to the configured admin mass mail channel.

/mbdiscord update and /mbdiscord update confirm stage a jar for the next restart. They do not hot-swap the running plugin. If a newer jar is already staged, DiscBridge tells admins to restart instead of staging again.

MailboxGUI-DiscBridge admin command help page — Admin command help page showing diagnostics, reload, update, and test commands.

MailboxGUI-DiscBridge admin status output in LOCAL mode — Admin status output for LOCAL mode.

MailboxGUI-DiscBridge test DM command output — Test DM command confirming DiscordSRV account linking and bot direct-message access.

MailboxGUI-DiscBridge test channel command output — Test channel command confirming the configured admin mass-mail channel can receive bot messages.

Permissions

Permission	Purpose
`mailboxguidiscbridge.use`	Use player commands.
`mailboxguidiscbridge.online`	Use online DM preference commands.
`mailboxguidiscbridge.ignore`	Use player ignore, unignore, and ignorelist commands.
`mailboxguidiscbridge.ignoreadmin`	Use ignoreadmin and unignoreadmin commands.
`mailboxguidiscbridge.admin`	Base admin access.
`mailboxguidiscbridge.admin.reload`	Reload bridge config, language files, and player data.
`mailboxguidiscbridge.admin.status`	View admin status and mode diagnostics.
`mailboxguidiscbridge.admin.test`	Run test DM and test channel diagnostics.
`mailboxguidiscbridge.admin.update`	Run update checks and stage updates.

Language Files

Language files are stored in /plugins/MailboxGUI-DiscBridge/language/. The language file-version for MailboxGUI-DiscBridge 1.0.0 is 2.

Command messages are language-file based. Discord DM and channel templates remain in config.yml. Client locale detection can use a player's Minecraft client language for /mbdiscord command messages when supported.

messages_de.yml

messages_en.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_tw.yml

Config and Language Synchronization

The config synchronizer upgrades 0.1.0-Beta style config to the 1.0.0 layout.
Existing custom values are preserved where possible.
The old default server-name ImagineCraft is changed to generic Minecraft Server if it was not customized.
The language synchronizer adds missing keys and preserves customized language values where possible.
Backups are placed under /plugins/MailboxGUI-DiscBridge/backups/.

Update System

DiscBridge 1.0.0 uses the website release system. Config exposes only the update channel: release, beta, or alpha. Update URLs are built into the plugin.

/mbdiscord admin updatecheck checks current/latest/type/summary.
/mbdiscord update prepares an available update.
/mbdiscord update confirm stages the jar for the next restart.
The staged download is validated as a newer MailboxGUI-DiscBridge jar.

MailboxGUI-DiscBridge update check command output — Website-powered update check showing current version, latest version, update type, summary, and download information.

Troubleshooting

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

NETWORK_NODE Disables on Startup

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

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.