Developer API

Send items to a player's mailbox from your own plugin, with a safe fallback when AT-MailBox is missing.

Other plugins can deliver items through AT-MailBox. Delivery tries the inventory first, then routes overflow to the mailbox. If AT-MailBox is not installed, the call falls back to a plain inventory add so items are never lost.

Setup

Add AT-MailBox as a depend or soft-depend in your plugin.yml:

softdepend:
  - AT-MailBox

Then call the static MailboxAPI:

import cc.arrowtan.atmailbox.api.MailboxAPI;
import cc.arrowtan.atmailbox.api.DeliveryResult;

Delivering items

deliver takes a player and one or more item stacks. It returns a map of each item to its outcome. Call it on the main thread.

Map<ItemStack, DeliveryResult> results = MailboxAPI.deliver(player, item);

Delivery outcomes

Result	Meaning
`DELIVERED`	Went straight into the player's inventory.
`QUEUED`	Inventory was full, so the item went to the mailbox.
`MAILBOX_FULL_DROPPED`	Mailbox was full, so the item was dropped at the player's feet.
`MAILBOX_FULL_REJECTED`	Mailbox was full and drop-at-feet is off, so the item was not delivered.

When AT-MailBox is not installed, deliver adds the items straight to the player's inventory and reports DELIVERED, so nothing is lost. Guard with isAvailable() if you need to know whether the mailbox is actually present.

Reading state

boolean ok      = MailboxAPI.isAvailable();
int unclaimed   = MailboxAPI.getCount(uuid);
int capacity    = MailboxAPI.getCapacity(player);
int pages       = MailboxAPI.getPageCount(player);
int slotsPerPg  = MailboxAPI.getSlotsPerPage();

Method	Returns
`isAvailable()`	Whether AT-MailBox is installed and enabled.
`getCount(UUID)`	The player's unclaimed item count.
`getCapacity(Player)`	Total capacity: pages times slots per page.
`getPageCount(Player)`	The player's page count from their capacity tier.
`getSlotsPerPage()`	The configured slots per page.

When AT-MailBox is missing, the read methods return safe defaults (0, or false for isAvailable).

Capacity tiers explains page counts and capacity.
Overflow capture explains the full-mailbox behaviour.

Setup

Delivering items

Delivery outcomes

Reading state

Related pages

On this page