AT-MailBox | Never Lose Items Again v1.0.0

---

Overview

Players lose items all the time. Their inventory fills up mid-grind, the next pickup spills onto the ground, and it's gone before they notice. AT-MailBox catches that overflow. When a player picks up an item with no room left, it goes into their personal mailbox instead, saved in your server database and claimed later through a clean paginated GUI. No more lost drops, no more "the server ate my items" tickets.

---

Dependencies

Required: AT-MailBox runs on TheAPI (version 13.8.x or newer), which must be installed separately or the plugin will not load. It's a free, single-jar library that powers the GUIs, config, and database handling.


Optional:

• PlaceholderAPI for the %atmailbox_...% placeholders (link)
• InfiniteBags routes overflow straight into a player's bag when they have one (link)

---

How It Works

• Catches overflow automatically: when a player picks up an item with a full inventory, it's routed to their mailbox instead of dropping on the ground
• Claim through a GUI: players open /mailbox to see their stored items, claim one at a time, or claim everything at once
• Never silently lost: if the mailbox itself is full, you choose whether the item drops at the player's feet or is rejected with a message

---

⚙ Player Settings

Each player controls how their mailbox behaves through an in-GUI settings menu, opened right from the mailbox.

• Auto-send existing types: overflow is sent to the mailbox only for item types the player already has stored there
• Auto-send everything: all overflow is routed to the mailbox
• Each player's choices are saved, so the mailbox works the way they want it to

---

🗃 Rank-Based Capacity

Mailbox size is driven by permission tiers, so you can reward ranks and donors with bigger mailboxes.

• Capacity is measured in pages, and each tier grants a page count (the default config ships default, vip, mvp, and unlimited)
• Tiers are fully config-driven, so add, rename, or remove them freely. Each tier <name> auto-grants the permission atmailbox.capacity.<name>
• The highest tier a player has wins, with default as the floor for everyone

---

Item Expiry

• Optional expiry: stored items can expire after a configurable number of days, keeping your database tidy (or turn it off entirely)
• Expiry warnings: players are warned on join and optionally on a repeating timer while online, so they have a chance to claim before items are purged
• Live countdown: items close to expiry show a "time left" note right in the GUI

---

Login Notifications

When a player joins with items waiting, they get a heads-up so the mailbox never goes unnoticed. Notifications come as a chat message, a title, and a sound, each toggleable, with a cooldown so it never spams. Players with the bypass permission can opt out.

---

🖥 Clean GUI

• A paginated mailbox viewer with a 3-row or 6-row layout (your choice)
• Left-click an item to claim it, or hit Claim All to take everything that fits
• Configurable title, filler, and per-action sounds (open, claim, claim-all, page-turn)
• Items are never stolen or lost on a partial claim, anything that doesn't fit stays safely in the mailbox

---

Commands

• /mailbox (alias /mb) open your mailbox
• /mailbox admin open <player> view a player's mailbox
• /mailbox admin deliver <player> send an item straight to a player's mailbox
• /mailbox admin clear <player> empty a player's mailbox
• /mailbox admin reload reload config and language files

---

Permissions

• atmailbox.use open and claim from the mailbox (default: true)
• atmailbox.admin all admin commands (default: op)
• atmailbox.capacity.<tier> grants that tier's mailbox size
• atmailbox.notify.bypass skip the login notification

---

PlaceholderAPI

• %atmailbox_count% / %atmailbox_slots_used% items currently stored
• %atmailbox_capacity% total mailbox capacity
• %atmailbox_slots_free% remaining space
• %atmailbox_has_items% whether the mailbox has anything in it

---

Compatibility

• Minecraft: 1.21 and newer
• Server software: Spigot, Paper
• Java: 17 or higher
• Storage: SQLite by default, with MySQL, MariaDB, and H2 also supported
• Languages: English, Spanish, and French bundled, with easy custom translations

---

Developer API

Other plugins can deliver items through MailboxAPI: deliver to a player, check availability, and read their count, capacity, page count, and slots per page. If AT-MailBox isn't installed, deliver falls back to a plain inventory add, so items are never lost.

---

Metrics

This plugin uses bStats to collect anonymous usage stats. You can opt out anytime in plugins/bStats/config.yml.

---

Support & Docs

Full setup and configuration guides are in the documentation. Need help, found a bug, or want to suggest a feature? Join the Discord.