GroupeZ Docs
Modules

Mailbox Module

Offline item delivery and text mails for players, online or offline

File: modules/mailbox/config.yml

The Mailbox module provides two complementary features:

  • Item mailbox: administrators send physical items to a player's virtual mailbox, even when the player is offline. The player opens the mailbox GUI to collect the items, which expire after a configurable duration.
  • Text mails: players send short text messages to another player, online or offline. The recipient reads them with /mail read, and is notified on join when unread mails are waiting.

Source Configuration

enable: true

# The expiration time of items when added to the mailbox
# If the player does not recover his items with expiration they will be deleted permanently.
expiration: 86400

# Settings of the text mails, sent with /mail send <player> <message>
# A mail can be sent to an offline player, it will be readable with /mail read on his next connection.

# Notify the player when he connects and has unread mails
message-notify-on-join: true

# Delay in seconds before sending the notification, to avoid it being lost in the join messages
message-notify-delay: 3

# Maximum amount of mails a player can store, a new mail is refused when the limit is reached
message-max-amount: 50

# Maximum amount of characters of a mail
message-max-length: 256

# Delay in seconds between two mails sent by the same player
# Players with the permission essentials.bypass.cooldown are not affected
message-cooldown: 5

# Date format used to display the date of a mail
message-date-format: "yyyy-MM-dd HH:mm"

Options

Item Mailbox

OptionTypeDefaultDescription
enableBooleantrueEnable or disable the Mailbox module (item mailbox and text mails)
expirationInteger86400Time in seconds before an uncollected item expires and is permanently removed from the mailbox. 86400 seconds = 24 hours

When items expire, they are permanently deleted and cannot be recovered. The expiration date of an item is computed when the item is added (now + expiration), so a value of 0 makes items expire immediately: always use a positive value. For a very long retention, use a large value such as 2592000 (30 days).

Text Mails

OptionTypeDefaultDescription
message-notify-on-joinBooleantrueNotify a player who joins with unread mails. The notification contains a clickable /mail read
message-notify-delayInteger3Delay in seconds before the join notification is sent, so it is not lost among the other join messages (minimum 1)
message-max-amountInteger50Maximum number of mails a player can store. When the limit is reached, new mails to that player are refused
message-max-lengthInteger256Maximum number of characters of a mail
message-cooldownInteger5Delay in seconds between two mails sent by the same player. 0 disables the cooldown. Players with essentials.bypass.cooldown are not affected (when enable-cooldown-bypass is true in config.yml)
message-date-formatStringyyyy-MM-dd HH:mmDate format used in /mail read. Follows Java SimpleDateFormat patterns

Item Mailbox

  1. An administrator sends an item to a player's mailbox with /mail give, /mail give-hand, /mail giveall or /mail giveall-hand.
  2. The item is stored in the recipient's virtual mailbox, whether the recipient is online or offline. An online recipient receives an action bar message.
  3. The player opens their mailbox with /mail and clicks on the items to collect them (a free inventory slot is required).
  4. If an item is not collected before its expiration date, it is removed.
  5. Administrators can inspect another player's mailbox with /mail open <player> and empty it with /mail clear <player>.

SQL storage required

The item mailbox requires a SQL storage (SQLITE, MYSQL, MARIADB or HIKARICP). It is not implemented for the JSON storage.

Text Mails

Text mails let players leave a message to someone who is not connected.

  • /mail send <player> <message> sends a mail to an online or offline player. An online recipient is notified immediately with a message pointing to /mail read.
  • /mail read displays all your mails, with the sender and the date, then marks them as read.
  • /mail clearmessages deletes your own mails; /mail clearmessages <player> deletes the mails of another player.
  • /mail sendall <message> sends a mail to every online player (the sender is skipped, as well as players whose mailbox is full).
  • When a player joins with unread mails, they receive a clickable notification after message-notify-delay seconds (if message-notify-on-join is enabled).

Restrictions

  • A mail cannot be longer than message-max-length characters.
  • A player cannot send a mail to themselves.
  • A muted player cannot send mails.
  • A player who used /ignore on the sender does not receive their mails (the sender is told the recipient does not want to receive them). The ignore list is checked when the recipient is online.
  • A mail is refused when the recipient already stores message-max-amount mails.
  • Players must wait message-cooldown seconds between two mails, unless they have essentials.bypass.cooldown.
  • Mails sent from the console are signed with the console name and are not subject to the mute and cooldown checks.

Storage

Text mails work with every storage type:

StoragePersistence
SQLITE, MYSQL, MARIADB, HIKARICPuser_mail_messages table
JSONStored inside the player's user file

Unlike text mails, the item mailbox is only available with a SQL storage.

CommandAliasesPermissionDescription
/mailmailbox, mbessentials.mailOpen your item mailbox

Mail Subcommands

SubcommandPermissionDescription
/mail open <player>essentials.mail.openOpen the item mailbox of a player (admin view)
/mail give <player> <item> [amount]essentials.mail.giveSend an item (vanilla material or custom item from the Items module) to a player's mailbox
/mail give-hand <player>essentials.mail.give.handSend the item you are holding to a player's mailbox
/mail giveall <item> [amount]essentials.mail.giveallSend an item to the mailbox of every online player
/mail giveall-handessentials.mail.giveall.handSend the item you are holding to the mailbox of every online player
/mail clear <player>essentials.mail.clearRemove every item from a player's mailbox
/mail send <player> <message>essentials.mail.sendSend a text mail to a player, online or offline
/mail readessentials.mail.readRead the mails you received and mark them as read
/mail sendall <message>essentials.mail.send.allSend a text mail to every online player
/mail clearmessages [player]essentials.mail.clear.messagesDelete your mails, or the mails of another player
PermissionDescription
essentials.bypass.cooldownIgnore message-cooldown between two text mails

For the full command list, see Commands & Permissions.

PlaceholderDescription
%zessentials_user_mailbox_items%Returns the number of items currently in the player's item mailbox

Use the %zessentials_user_mailbox_items% placeholder in scoreboards, holograms, or chat formats to show players how many uncollected items they have. For example, you could display a notification in the scoreboard when the value is greater than zero.

For the full placeholder list, see Placeholders.

Examples

7-Day Item Expiration

expiration: 604800

Items expire after 7 days, giving players more time to log in and collect deliveries.

Stricter Text Mails

message-max-amount: 20
message-max-length: 128
message-cooldown: 30
message-date-format: "dd/MM/yyyy HH:mm"

Players can store at most 20 mails of 128 characters, and must wait 30 seconds between two mails.

Disable the Join Notification

message-notify-on-join: false

Players are no longer notified on join; they must run /mail read themselves.

Kits Module

Configurable kit system with cooldowns and first-join kits

Messages Module

Private messaging system with reply and social spy support

On this page

Source ConfigurationOptionsItem MailboxText MailsItem MailboxText MailsRestrictionsStorageRelated CommandsMail SubcommandsRelated PlaceholdersExamples7-Day Item ExpirationStricter Text MailsDisable the Join Notification
GroupeZ MCP

Documentation in your AI

MCP lets your AI search GroupeZ documentation and read current examples to help you configure your plugins.

Read-only · No documentation API key needed

1. Copy the server URL

Transport: HTTP (Streamable HTTP). Authentication: none. Your tool uses its own model and subscription limits.

  1. Open Plugins in ChatGPT on the web, then + → Add custom MCP server.
  2. Name it ‘GroupeZ Documentation’, paste the URL above and choose ‘No authentication’. Create and install the plugin.
  3. In a conversation, type @ and select the plugin before asking. If needed, enable search, get_page and list_pages in its settings.
Official setup guide

3. Ask a question

Use GroupeZ MCP to help me create a zMenu inventory. Search relevant pages, read the examples and cite your sources.
Other clients and troubleshooting

For clients using mcpServers, adapt this example to their format:

{
  "mcpServers": {
    "groupez-docs": {
      "url": ""
    }
  }
}

Available tools are search, get_page and list_pages. Refresh the connector’s tools after updates. If your AI cannot access them, check that the connector is enabled in the conversation and your account allows custom MCP servers. Opening the URL in a browser is not an MCP test.