### SQLite startup console output

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

Example console output when MailboxGUI starts with SQLite storage. The exact wording can vary by version and configuration. It shows the storage backend, database file path, player data path, and Post Office data path.

```text
[MailboxGUI] Storage Backend: SQLITE
[MailboxGUI] SQLite database file: plugins/MailboxGUI/data/data.db
[MailboxGUI] Player data path: plugins/MailboxGUI/data/playerdata
[MailboxGUI] Post Office data path: plugins/MailboxGUI/data/postofficedata
[MailboxGUI] MailboxGUI storage provider initialized successfully.
```

--------------------------------

### Vote reward examples with /mba sp, sm, sl, sla

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

Vote reward examples using /mba sp, sm, sl, and sla with the %player% placeholder and --from VoteRewards. These commands are suitable for vote reward plugins and other server automation.

```text
/mba sp %player% diamond:3 emerald:8 xp:250 --from VoteRewards
/mba sm %player% 500 --from VoteRewards
/mba sl %player% 'Thanks for voting! Your reward has been delivered by mail.' --from VoteRewards
/mba sla %player% 'Thanks for voting today!' --title Thanks --from VoteRewards --delay 30
```

--------------------------------

### Example network/config.yml

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

Example network/config.yml for a backend. Enables network mode, sets a unique server-id and display name, requires shared storage, and configures MySQL and Redis.

```yaml
network:
  enabled: true
  server-id: live
  server-display-name: 'Live'
  require-shared-storage: true

mysql:
  require-active-storage-type: MYSQL

redis:
  host: 172.18.0.1
  port: 6379
  password: 'change-this'
  database: 0
  use-ssl: false
```

--------------------------------

### Admin/server display placeholder usage

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

Admin/server display placeholder usage example. Shows storage backend, queued delayed mail, registered mailboxes, and post office mailbox counts. Requires PlaceholderAPI installed and the hook registered.

```text
Storage: %mailboxgui_storage_type%
Queued Mail: %mailboxgui_delayed_mail_queued%
Registered Mailboxes: %mailboxgui_registered_mailboxes%
Post Office Boxes: %mailboxgui_postoffice_mailboxes%

```

--------------------------------

### Storage Conversion Success Example

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

Example successful conversion output from YAML to SQLITE. This is a conceptual flow, not a guaranteed exact console copy for every version.

```text
[MailboxGUI] Starting storage conversion: YAML -> SQLITE
[MailboxGUI] Saving loaded mailbox and Post Office data before conversion...
[MailboxGUI] Backup created: plugins/MailboxGUI/data/backups/storage-conversions/20260510-184522-YAML-to-SQLITE
[MailboxGUI] Copied player data entries: 42
[MailboxGUI] Copied Post Office data: yes
[MailboxGUI] Updated config.yml storage.type to SQLITE
[MailboxGUI] Reloaded storage provider and mailbox data.
[MailboxGUI] Storage conversion completed successfully.

```

--------------------------------

### MySQL Storage Configuration Example

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

Example MySQL storage configuration. The database and user should exist before switching to `MYSQL`. MailboxGUI validates the connection and creates or validates tables `mailboxgui_playerdata` and `mailboxgui_postoffice`; the Post Office data row uses internal id `mailboxes`. If validation fails on startup, MailboxGUI falls back to `SQLITE`. Network mode requires all backends to use the same shared MySQL/MariaDB database.

```yaml
storage:
  type: MYSQL

  mysql:
    host: 127.0.0.1
    port: 3306
    database: mailboxgui
    username: mailboxgui_user
    password: 'change-this-password'
    use-ssl: false

```

--------------------------------

### Scoreboard-style placeholder usage

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

Scoreboard-style placeholder usage example. Shows how to display mailbox registration, inbox total, and pending mail using MailboxGUI placeholders. Requires PlaceholderAPI installed and the hook registered.

```text
Mailbox: %mailboxgui_mailbox_registered%
Inbox: %mailboxgui_inbox_total%
New Mail: %mailboxgui_pending_total%

```

--------------------------------

### Legacy import example: /mba networkindex and /mailbox admin import player

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

Commands for importing a legacy player. Run /mba networkindex on the Legacy backend to index OldPlayer123, then /mailbox admin import player OldPlayer123 on Live to create MailboxGUI data from the shared network player index.

```text
/mba networkindex

```

```text
/mailbox admin import player OldPlayer123

```

--------------------------------

### MailboxGUI storage config example

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

Configure the storage backend for MailboxGUI. The type can be YAML, SQLITE, or MYSQL; fresh installs default to SQLITE. The sqlite file path is relative to plugins/MailboxGUI/, and the mysql block defines the database connection. Changing storage.type alone does not copy existing data; use the conversion command for that.

```yaml
storage:
  # Valid types: YAML, SQLITE, MYSQL
  # Fresh installs default to SQLITE.
  # Legacy YAML upgrades may stay on YAML automatically for safety.
  type: SQLITE

  sqlite:
    # Path is relative to plugins/MailboxGUI/
    file: data/data.db

  mysql:
    host: localhost
    port: 3306
    database: mailboxgui
    username: root
    password: ''
    use-ssl: false
```

--------------------------------

### Admin send-mail practical examples with /mba sl, sla, sp, sm, scod

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

Practical admin send-mail examples for vote rewards, GUI shops, crates, quests, compensation, events, daily/login rewards, console automation, command blocks, and server scripts. Quoted --from values preserve spaces, color codes, Unicode, and punctuation; malformed quoted sender names fail clearly. Use r:admin when COD payment or returned contents should go to the Shared Admin Inbox.

```text
/mba sl Rismr1 'Welcome to the new season!' --from "ImagineCraft Staff" --expire 7d
/mba sla allplayers 'Read the full event rules in this book.' --title "Summer Event" --from "ImagineCraft Events" --expire 14d
/mba sp Rismr1 t:starter_bundle:1 xp:500 --from "ImagineCraft Quest Rewards" --delay 30 --expire 7d
/mba sm offlineplayers 250 --from "Daily Login Rewards" --expire 3d
/mba scod Rismr1 p:1000 r:admin t:rare_pickaxe:1 --from "Server Market" --expire 2d
```

--------------------------------

### Network mode startup validation output

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

Startup/validation output when network mode starts successfully. Shows the expected log lines for a backend with server-id live.

```text
[MailboxGUI] Network mode enabled for server-id live (Live).
[MailboxGUI] Active storage: MYSQL.
[MailboxGUI] Shared storage requirement satisfied.
[MailboxGUI] Redis connection established.
[MailboxGUI] Network coordination ready.
```

--------------------------------

### Backend server-id examples: live and legacy

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

Two YAML configurations for the network section of config.yml. The first sets server-id to 'live' and the second to 'legacy'. Both enable network mode and set a display name. Use a different server-id on every backend.

```yaml
network:
  enabled: true
  server-id: live
  server-display-name: 'Live'

```

```yaml
network:
  enabled: true
  server-id: legacy
  server-display-name: 'Legacy'

```

--------------------------------

### Admin send-mail item token examples

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

Example item tokens for admin send-mail package commands. Shows material:amount, xp:amount, template:<id>:amount, and t:<id>:amount forms. Materials use Bukkit/Minecraft material names, xp adds package experience, and templates use saved item templates.

```text
stone:64
diamond:3
xp:250
template:starter-kit:1
t:rare-sword:1
```

--------------------------------

### MailboxGUI startup configuration error console output

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

Example console output shown when MailboxGUI fails to load its configuration. The exact wording may vary by version, but this pattern indicates a YAML formatting problem in config.yml, such as incorrect spacing, quotes, or list formatting.

```text
[MailboxGUI] Enabling MailboxGUI...
[MailboxGUI ERROR] Failed to load configuration.
[MailboxGUI ERROR] Check config.yml spacing, quotes, and list formatting.
```

--------------------------------

### plugin.yml softdepend setup

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

Declare MailboxGUI as a soft dependency in your plugin.yml. Use softdepend when your plugin can run without MailboxGUI but enables integration when present; use depend when your plugin cannot function without it.

```yaml
softdepend: [MailboxGUI]
```

--------------------------------

### Get MailboxGUIApi via MailboxGUIApiProvider

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

Retrieve the MailboxGUI API instance using MailboxGUIApiProvider.get(). It can return null if MailboxGUI is not installed or the service is not registered yet; perform this lookup after plugins are enabled, not during static initialization.

```java
import com.rismr1.mailboxgui.api.MailboxGUIApi;
import com.rismr1.mailboxgui.api.MailboxGUIApiProvider;

MailboxGUIApi mailboxApi = MailboxGUIApiProvider.get();

if (mailboxApi == null) {
    getLogger().warning("MailboxGUI API is not available.");
    return;
}
```

--------------------------------

### Configure package core settings

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

Core package configuration. `enabled` defaults to true. `deny-loaded-shulker-box` defaults to true, blocking non-empty shulker boxes. `size-in-rows` defaults to 3 (valid: 1, 2, or 3; 1 row = 7 slots, 2 rows = 14, 3 rows = 21). `delivery-delay-seconds` defaults to 0 (immediate). `admin-server-name` defaults to '&a&lServer' and supports color codes.

```yaml
package:
  enabled: true
  deny-loaded-shulker-box: true
  size-in-rows: 3
  delivery-delay-seconds: 0
  admin-server-name: '&a&lServer'
```

--------------------------------

### MySQL fallback console output

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

Example console output shown when MySQL validation fails during startup. MailboxGUI logs severe/red error messages, updates config.yml storage.type to SQLITE, and starts on SQLite instead of failing the whole plugin startup. Exact wording may vary by version and configuration.

```text
[MailboxGUI ERROR] Failed to connect to MYSQL storage.
[MailboxGUI ERROR] MySQL validation failed during startup.
[MailboxGUI ERROR] Falling back to SQLITE so MailboxGUI can continue loading.
[MailboxGUI] Updated config.yml storage.type to SQLITE.
[MailboxGUI] Storage Backend: SQLITE
[MailboxGUI] SQLite database file: plugins/MailboxGUI/data/data.db
```

--------------------------------

### Configure package experience settings

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

Configures raw experience in packages. `enabled` defaults to true. `max-experience-per-package` defaults to -1 (no plugin cap); positive values set the maximum raw XP a normal player can add. `withdraw-from-sender-on-send` defaults to true, removing XP from the sender when sent; false disables withdrawal.

```yaml
package:
  experience:
    enabled: true
    max-experience-per-package: -1
    withdraw-from-sender-on-send: true
```

--------------------------------

### Shop/GUI menu mail commands

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

Use these commands in a shop or GUI menu plugin to deliver purchased items, XP, or money by mail. The %player% placeholder is replaced by the buying player, and the --from flag labels the sender as ServerShop.

```text
/mba sp %player% t:starter_bundle:1 --from ServerShop
/mba sp %player% diamond_pickaxe:1 xp:500 --from ServerShop
/mba sm %player% 2500 --from ServerShop
```

--------------------------------

### Dynmap Enabled

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

Enables or disables MailboxGUI Dynmap integration. Default is true. Dynmap is optional; markers only work when Dynmap is installed, enabled, and compatible with the server version.

```yaml
dynmap:
  enabled: true
```

--------------------------------

### Send admin COD packages with /mba scod

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

Use these commands to send admin-origin COD packages via /mba scod. The price can be the first token or use p:/price: when the sender name needs to be unambiguous. r:<returnPlayer> controls both COD payment return and declined package content return; without it, admin/API COD packages use sink behavior for accepted payments and declined contents.

```text
/mba scod Rismr1 ICServices 1000 r:Rismr1 template:rare_pickaxe:1 diamond:64
/mba scod Rismr1 ServerShop diamond:8,emerald:4 r:Rismr1 template:rare_pickaxe:1
/mba scod allplayers ServerShop diamond:3,xp:250 r:Rismr1 template:event_key:1
```

--------------------------------

### SQLite Database Path

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

Default SQLite database file path. SQLite is the default for fresh installs and keeps plugin data in a local database file. Back up `data/data.db` before major upgrades or conversions.

```text
plugins/MailboxGUI/data/data.db

```

--------------------------------

### Configure Redis for network mode

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

Configures Redis for network mode. Redis must be reachable by every backend and should be the same instance on every backend. In Docker/Pterodactyl setups, 127.0.0.1 usually means inside the Minecraft container, not the Ubuntu host.

```yaml
redis:
  host: 172.18.0.1
  port: 6379
  password: 'change-this'
  database: 0
  use-ssl: false
```

--------------------------------

### Storage Conversion Command

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

Storage conversion commands. `current` shows the active backend; the target form converts from the active backend to the selected backend. Same-target conversion is refused. Requires `mailboxgui.admin.convert` or `mailboxgui.admin`. Conversion to `MYSQL` validates MySQL before changing config. Convert before enabling network mode; conversion is hidden/refused when `network.enabled=true`. Backups are created before overwriting target storage and stored under `plugins/MailboxGUI/data/backups/storage-conversions/`.

```text
/mailbox admin convert current
/mba convert current

/mailbox admin convert <YAML|SQLITE|MYSQL>
/mba convert <YAML|SQLITE|MYSQL>

Examples:

/mailbox admin convert SQLITE
/mailbox admin convert MYSQL
/mba convert YAML

```

--------------------------------

### Dynmap Marker Set

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

Configures the Dynmap marker set. Defaults: id mailboxgui-mailboxes, label Mailboxes/PO Boxes/NPC, hide-by-default false, layer-priority 10. hide-by-default true starts the layer hidden; layer-priority sets Dynmap layer ordering priority.

```yaml
dynmap:
  marker-set:
    id: 'mailboxgui-mailboxes'
    label: 'Mailboxes/PO Boxes/NPC'
    hide-by-default: false
    layer-priority: 10
```

--------------------------------

### Conversion Backup Folder Structure

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

Shows the conversion backup folder structure. The timestamp and conversion direction are included in the folder name. The backup includes `config.yml`, a source provider snapshot, and a target snapshot if target data already existed before it was cleared. This backup is important because conversion clears the target before copying data.

```text
plugins/
└── MailboxGUI/
    └── data/
        └── backups/
            └── storage-conversions/
                └── 20260510-184522-YAML-to-SQLITE/
                    ├── config.yml
                    ├── source/
                    │   ├── playerdata/
                    │   └── postofficedata/
                    └── target-before-clear/
                        └── ...

```

--------------------------------

### Configure package experience item

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

Configures the special package XP item. `material` defaults to EXPERIENCE_BOTTLE. `display-name` defaults to '&aExperience Package'. `lore` supports %experience% and is shown on redeemable XP items. `cod-preview-lore` also supports %experience% and is shown while previewing unpaid COD packages.

```yaml
package:
  experience:
    item:
      material: EXPERIENCE_BOTTLE
      display-name: '&aExperience Package'
      lore:
        - '&7Stored Experience: &a%experience%'
        - '&e&lAny click to claim'
      cod-preview-lore:
        - '&7Stored Experience: &a%experience%'
        - '&cAccept COD Package before you can claim this XP'
```