✉ SmartMail
A simple, immersive in-game mail system for Paper & Spigot
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
■ What is SmartMail?
SmartMail lets players send letters and item packages to each other through a clean GUI — no chat commands, no hassle. Open your inbox, read your mail, attach items, and track whether your letter was delivered and read. Everything runs off the main thread so there's zero impact on server performance.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
■ Features
Compose GUI — Running /mail send opens a chest GUI where you can drop an item into the attachment slot and click Send when you're ready. No accidental sends.
Delivery tracking — Every letter shows its current status: SENT → DELIVERED → OPENED. Updates automatically when the recipient logs in.
Item attachments — Shift-click or place any item into the attachment slot before sending. If something goes wrong on send, your item is always returned to you.
Return to sender — One button in the reading view sends the letter and any unclaimed item back to whoever sent it. Already-returned mail won't show the button again.
Notifications — When you log in with unread mail you get a chat message, a sound, and an actionbar reminder that pulses a few times so you don't miss it. Online players get notified the moment mail arrives.
Unread glow — Unread letters glow in your inbox. Once read they go back to a normal paper icon. Makes it easy to spot what needs attention.
Paginated inbox — Supports as many letters as you want with previous/next page buttons, an unread count in the title, and an empty mailbox placeholder when there's nothing.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
■ GUI Previews
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
■ Commands & Permissions
Commands
Code:
/mail — Open your inbox
/mail send <player> <message> — Open the compose window to write and send a letter
/mail reload — Reload the config (admin only)Permissions
Code:
smartmail.use — Open inbox and receive mail (Default: true)
smartmail.send — Send mail to other players (Default: true)
smartmail.admin — Reload config (Default: op)━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
■ Storage & Performance
- SQLite with WAL mode — Faster reads and writes with no database stutters, even during busy periods.
- Auto migration — The plugin handles any database changes automatically on startup. No manual SQL needed.
- Fully async — Every database read and write happens off the main thread. Callbacks return safely to the main thread when done.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
■ Configuration
Everything is configurable in config.yml and can be reloaded with /mail reload — no restart needed.
Code:
gui:
title: "&8✉ Post Office Box"
unread-glow: true
unread-mail-material: MAP
read-mail-material: PAPER
border-material: CYAN_STAINED_GLASS_PANE
compose:
return-item-on-cancel: true
notifications:
action-bar:
enabled: true
message: "&b✉ You have %count% unread letter(s)! (/mail)"
sounds:
open-mailbox: BLOCK_CHEST_OPEN
new-mail: ENTITY_EXPERIENCE_ORB_PICKUP
send-mail: ENTITY_ARROW_SHOOT
delete-mail: ENTITY_ITEM_BREAK
error: ENTITY_VILLAGER_NO━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
■ Roadmap
The architecture is built to be expandable. Planned additions include (v2.0.0+):
- NPC Postman — a Villager that walks to you and plays a delivery animation
- Reply button — reply to a letter directly from the reading view
- Mail expiry — letters auto-delete after a set number of days
- Inbox limit — cap how many letters a player can receive to prevent spam
- Read receipts — get notified when your letter is opened
- Mail blocking — block mail from specific players
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
■ BUG REPORTS & COMMUNITY SUPPORT
Response times may vary but every report is read and taken seriously. Most bugs can be patched same day.
