Mail Delivery

Overview

I built Mail Delivery as a fun addition for Minecraft towns, cities, and shared survival worlds. I always liked the idea of having a real postal system in-game, but on most worlds item trading ends up being clunky. Someone is offline, a chest at spawn becomes the drop-off spot, or there is no easy way to leave a note for one specific player. This addon adds a proper mailbox system so players can send items, packages, and letters in a way that feels like it belongs in the world.

It works especially well on survival servers, realms, and community worlds where players are building towns that feel lived in. Mail is stored in world dynamic properties, so it survives restarts and pack updates. The whole addon runs on the stable Script API with no experiments, and it is fully achievement safe.

Key features:

• Craftable mailboxes with 10 wood post variants plus a wall mailbox
• Recolor any mailbox with any of the 16 dyes, and strip post mailboxes with an axe
• Mail Deposit Box for instant public drop-offs
• Open and Sealed Packages that hold up to 54 stacks of items (same as a double chest)
• Written letters for messages without items
• Per-player friends list (up to 60) for quick recipient picking
• 4 delivery schedules: Noon, Hourly, Every X days, or Immediate
• Full admin toolkit: settings, item blacklist, audit log, mailbox inspection, cleanup, and server-wide letter broadcast
• Auto-return of undeliverable mail and configurable send cooldown
• One-time Guide Book handed out on first join, with a full in-game reference

Installation

Both the Behavior Pack and the Resource Pack must be enabled on the world. The mailbox and package block models live in the RP, so the addon will look broken if only the BP is applied. Both packs ship in the single .mcaddon import.

Mail Delivery requires Minecraft Bedrock 1.26.0 or newer. No experimental toggles are required, and all mail, ownership, and settings persist in world dynamic properties so they survive restarts and pack updates.

Getting Started

The Guide Book

Every player is handed a Mail Delivery Guide the first time they join a world with this addon installed. Use the guide (right-click, or the interact button on mobile and controller) to open a 4-section in-game reference covering Info, How To, Recipes, and Admin Info. If a player somehow misses the one-time hand-out, the guide can also be crafted from a single sheet of paper.

The guide is intentionally the first thing a new player sees, so the addon is self-teaching. Admins get an extra Admin Controls button inside the guide that opens the full moderation panel.

Crafting Recipes

Every block and item in the pack is crafted at a standard crafting table:

Mailbox on Post

   I          I = Iron Ingot
   L          L = Log  (any type)
   C          C = Cobblestone

The log type you use decides the post style. Using spruce gives a spruce post, oak gives an oak post, and so on for all 10 wood types. Outputs 1 Mailbox on Post.

Wall Mailbox

   I          I = Iron Ingot
   P          P = Paper

Outputs 1 Wall Mailbox.

Mail Deposit Box

   B B B      B = (black top)
   I P I      P = Paper
   I I I      I = Iron Ingot

Outputs 1 Mail Deposit Box.

Open Package

   P P P      P = Paper
   P   P
   P P P

Outputs 1 Open Package. The center is left empty.

Mail Delivery Guide

   P          P = Paper

Outputs 1 Mail Delivery Guide. Players receive one automatically on first join.

Mailboxes

A mailbox is the core of the system. It's your personal inbox for receiving mail, your outbox for sending on a schedule, and the only block a recipient actually needs in the world.

Variants & Customization

Mail Delivery ships with 11 mailbox variants:

Post mailboxes are 2 blocks tall. Both halves belong to the same mailbox, and ownership is always stored on the base block so breaking either half correctly cleans up the claim.

Dyeing: hold any of the 16 dyes and interact with a Wall Mailbox or any Mailbox on Post to recolor it. All 16 colors are available, and the color sticks through breaks and replacements as long as the block stays.

Stripping: crouch (sneak) and interact with an axe on a post mailbox to strip the post, the same way you'd strip a log in vanilla. This only applies to post variants, not the wall mailbox.

Ownership

Placing a mailbox auto-claims it to whoever placed it. That player is now the owner, and only the owner or an admin can open it. Ownership is keyed to the exact block coordinates, so breaking the mailbox clears the claim and the next player to place one gets a fresh ownership record.

Admins are a deliberate exception. Placing a mailbox as an admin does not auto-claim it. Instead, the next time that mailbox is opened, the admin sees a Claim or Grant form where they can keep it, assign it to another player, or leave it unclaimed. This keeps staff from accidentally owning every mailbox they test.

The Mailbox Menu

Interact with any block of a mailbox to open it. Non-owners see a polite "this mailbox belongs to someone else" screen. The owner (and any admin) sees the full menu with these actions:

• Inbox — view and claim mail other players have sent you
• Outbox — view mail you've queued for the next scheduled pickup
• Send Item in Hand — queue the currently held item for a recipient
• Write Letter — compose a letter to queue for delivery
• Friends — manage your personal recipient list

The inbox and outbox each hold up to 60 entries, and one entry equals one send action. A single send of 64 stone is 1 entry, not 64, so you don't have to worry about filling your inbox with one careful bulk shipment.

Mail Deposit Box

The Mail Deposit Box is the instant version of the mailbox. Anyone can interact with it, it's not owned by anyone, and it sends mail immediately instead of queuing on a schedule. Think of it as a public drop-off at a post office instead of the mailbox attached to someone's house.

From a Deposit Box, any player can:

• Send Item in Hand — hold the item, open the box, pick a recipient and amount, done
• Write & Send Letter — compose and deliver a letter instantly
• Send a Sealed Package — if you're holding one

Deposit Boxes are 2 blocks tall, like post mailboxes. Place them in shared spaces: spawn, town squares, markets, trading halls, or wherever you want a communal mailing point.

Packages

Letters and single-stack sends are fine for small trades, but when you want to ship a full diamond set or a bulk resource order, you need a package. Packages are physical blocks that hold items, get sealed into a carryable item, and then mailed like any other send.

Open Package

Craft and place an Open Package anywhere. Interacting with it opens a UI where you can deposit items one at a time or use Bulk Deposit to dump a whole inventory section into it. An open package holds up to 54 stacks, which is the same as a double chest.

You can also set an optional recipient on the package while it's open. This labels it as To: <player> and pre-fills the recipient field when you go to mail it later. If you skip this, the package can still be mailed and you'll pick the recipient at send time.

When an Open Package has items inside, it automatically swaps its block model to show as "closed". It reopens visually when emptied. This is cosmetic so players can tell at a glance which packages on a shelf still have stuff in them.

Sealed Package

Breaking an Open Package that has items in it produces a Sealed Package, an item you can carry in your inventory. The sealed package keeps all its contents, the recipient label (if set), and its retention timer. You can:

• Send it as mail from a Deposit Box (instant)
• Send it from your Mailbox Outbox (scheduled)
• Place it back into the world as an Open Package if you need to edit the contents or add a recipient you forgot

Placing a sealed package back into the world turns it into an Open Package again with all its contents intact, so there's no penalty for "un-sealing" to fix a mistake.

Letters

A letter is a standalone text message, no item required. Letters can be composed from either a Deposit Box (instant delivery) or from your own Mailbox Outbox (scheduled delivery). Received letters show up in the recipient's inbox as a Letter item they can read.

By default, the addon allows multi-recipient letters, meaning a single letter can be sent to multiple players at once. Items and packages are always single-recipient. Admins can turn multi-recipient letters off under Settings if you want everything to be strictly one-to-one.

Friends List

Every player has a personal friends list, accessible from the mailbox menu. Adding someone to your friends list lets you pick them from a short list instead of searching the full player registry every time you mail something. The list holds up to 60 entries per player, with the oldest entries dropped first when you hit the cap.

Friends names are auto-refreshed from the player registry, so if someone changes their display name, your friends list updates the next time you open it.

Delivery Schedule

Mailbox outboxes process on a schedule chosen by the admin. Deposit Box sends always fire immediately and aren't affected by this setting. The 4 schedule modes are:

When a mailbox is full and can't accept incoming mail, the pending delivery is held and retried at the next pickup. After 3 failed pickups or 60 in-game days (whichever hits first), the mail is returned to the sender's mailbox as a return-to-sender entry.

Receiving Mail

When a player with waiting mail joins the world, they see a chat message telling them how many items are in their mailbox, and a note chime plays so they notice. From there, they walk up to their mailbox, open the Inbox, and claim individual entries. Claiming an entry moves the items into their inventory or drops them at their feet if their inventory is full.

Letters show up as a Letter item in the inbox. Claim it, hold it, and use it to read the message. Sealed packages work the same way: claim the entry to receive the sealed package as an inventory item, then place it or break it open to get at the contents.

Admin Guide

Admin Access

A player is treated as a Mail Delivery admin if either of these is true:

1. They are an Operator (/op <name>) — recommended
2. They have the admin tag — fallback

To grant admin access via tag (useful when OP detection isn't available):

/tag <player> add admin

To revoke:

/tag <player> remove admin

Admins open the admin panel from the Mail Delivery Guide by tapping Admin Controls. The panel has 5 sections: Settings, Item Blacklist, Audit Log, Mailbox Tools, and Broadcast Letter.

Settings

A single Modal form holds every admin setting:

Item Blacklist

The Item Blacklist blocks specific item IDs from being sent through mail or packed into packages. It's paginated, and the entry flow supports adding from your current inventory (just pick the item from a grid) or adding by item ID if you want to type it manually.

Some items are blocked by default for safety reasons: containers that could carry infinite nested inventories, maps, and a few addon items that don't survive serialization. When a player tries to send a blocked item, the UI explains why it was blocked instead of failing silently.

The blacklist can be cleared entirely from the Clear Blacklist button at the top of the page. Clear is confirmed before it runs.

Audit Log

When enabled, the audit log records admin actions and key events to a paginated log: admins opening or deleting other players' mail, cleanup actions, broadcast letters, blacklist changes, settings changes, and similar. The log is a ring buffer capped at the size you pick in Settings (10 to 150 entries, default 100), with the oldest entries dropped first when it fills up.

Each entry shows a short summary of what happened. There's a Clear Audit Log button at the top of the page that wipes the log after a confirmation.

Mailbox Tools

The Mailbox Tools page is where admins do hands-on moderation and cleanup:

• View / delete any player's Inbox — open a specific player's inbox and delete entries
• View / delete any player's Outbox — same thing for outbox entries
• Purge Old Mail — sweep through every mailbox and drop old entries
• Purge Unused Package Payloads — clean up orphaned sealed package contents whose owning package no longer exists
• Inactive Mailboxes (60+ days) — list every mailbox whose owner hasn't logged in for 60+ in-game days, useful for finding abandoned boxes

Broadcast Letter

The Broadcast Letter tool sends a single letter to every known mailbox owner in the world. It's useful for server-wide announcements that you want to leave in everyone's inbox rather than dropping into chat where it'll scroll away. The flow is: compose the letter, pick the recipient set (all known mailbox owners), and confirm. The send is recorded in the audit log.

Limits & Caps

Troubleshooting & FAQ

"The mailbox looks broken or the block is missing textures"

The most common cause of any problem with this addon is that only one of the two packs is enabled. Mail Delivery needs both the Behavior Pack and the Resource Pack applied to the world, and both should be at v1.0.0. Check the world's pack list before anything else.

"I placed a mailbox but I can't open it"

Make sure you're the player who placed it. Mailboxes are owned by the player who placed the block, and only the owner or an admin can open one. If an admin placed it for testing, the admin will see a Claim or Grant form the next time they open it, where they can assign it to you.

"My mail never arrived"

Check the delivery schedule under Admin Settings. If the server is on the default Noon schedule, mailbox outboxes only process once per in-game day at noon. Deposit Box sends always fire instantly, so try sending from a deposit box to confirm the pipeline works. If the recipient's inbox is full (60 entries), new mail waits and is returned to sender after 3 failed pickups.

"The package shows as closed when I didn't close it"

An Open Package automatically swaps to a "closed" model when it has items inside, and reopens visually when emptied. This is cosmetic so you can tell at a glance which packages still have stuff in them. It doesn't change how you interact with the block.

"I can't send an item, the UI says it's blocked"

That item is on the blacklist. Some items are blocked by default (containers, maps, some addon items) because they don't serialize safely. An admin can review the blacklist under Admin Controls and remove the entry if it's safe to mail.

"I'm hitting a send cooldown"

The default cooldown is 3 seconds between sends per player. Admins can change it under Settings (0 to 60 seconds, 0 disables it) and admins themselves always bypass the cooldown.

"I lost my Guide Book"

Craft a new one with a single sheet of paper at any crafting table. The one-time hand-out only fires once per player per world, but the recipe is always available.

Compatibility

• Bedrock version: 1.26.0 or newer (from manifest min_engine_version)
• Script API modules used: @minecraft/server 2.6.0, @minecraft/server-ui 2.0.0
• No experiments needed: works on vanilla worlds and realms
• Achievements: Safe. Using this addon does not disable achievements
• Cheats: Not required. Mail Delivery works in worlds with cheats off
• Multiplayer: Designed for it. Session state is cleaned up when players leave, and mail is stored in world dynamic properties shared across all players.
• Other JM addons: No known conflicts. Mail Delivery uses the jm_md: namespace exclusively for item IDs, block IDs, and dynamic properties.
• Custom blocks: Mail Delivery adds 22 block IDs (20 mailbox variants including tops and bottoms, 2 deposit box halves, 2 package states, and 1 wall mailbox). None overlap with vanilla.
• Worlds: All mail, ownership, friends lists, and settings persist across world saves and restarts via dynamic properties.