ImagineCraft Plugins
Back to MailboxGUI Wiki

Documentation • Public addon integration

MailboxGUI Developer API

MailboxGUI 6.0.0 • Archived version-specific API

Getting started

Start here: version & boundaries

This guide covers the public MailboxGUI 6.0.0 API from its archived source. It is a version-specific synchronous delivery/helper API, not the newer 6.1.0 service/query API. Private companion integration is excluded.

Use this API with the published 6.0.0 Free build. References below show the supported local-release surface; dormant future-edition declarations are deliberately omitted.

Back to the 6.0.0 wiki
Back to top ↑

Getting started

Compile locally & configure dependencies

  1. Obtain an authorized copy of the matching 6.0.0 source project, including the parent pom.xml and mailboxgui-api module. Do not substitute current main-branch code.
  2. Install a JDK compatible with the project’s Java 17 compiler target and Maven. Run the command below from the full archived project root.
  3. Use install, not deploy: this installs the parent POM/API jar into your local Maven cache. No public publishing account or repository upload is needed.
  4. Add the provided dependency below to your addon. Supply your own compatible Bukkit/Spigot compile dependency, because server classes are provided at runtime.
  5. Install the actual MailboxGUI 6.0.0 plugin jar on the server. The API artifact is a compile-time library, not a standalone mail plugin.
Build only the API and its parent locally
mvn -pl mailboxgui-api -am -DskipTests -Dgpg.skip=true install

The normal local cache is ~/.m2/repository/io/github/rismr1/mailboxgui-api/6.0.0/. Dependencies such as Spigot API and Maven build plugins may still need repository access. If signature generation is not configured, -Dgpg.skip=true skips signing for this local build; never add deploy or activate a publishing profile just to compile an addon.

Addon pom.xml — local artifact, not Maven Central
<dependency>
  <groupId>io.github.rismr1</groupId>
  <artifactId>mailboxgui-api</artifactId>
  <version>6.0.0</version>
  <scope>provided</scope>
</dependency>
Back to top ↑

Getting started

Plugin dependency & service discovery

Addon plugin.yml — hard dependency
name: ExampleAddon
version: 1.0.0
main: example.ExampleAddon
api-version: "1.18"
depend: [MailboxGUI]

For optional integration use softdepend: [MailboxGUI] and isolate API-dependent classes behind a plugin-presence check so absent API classes are not loaded. Handle later disable/service removal deliberately. A soft dependency is not permission to ignore a null service.

In onEnable(), after MailboxGUI is enabled
com.rismr1.mailboxgui.api.MailboxGUIApi api =
    getServer().getServicesManager().load(
        com.rismr1.mailboxgui.api.MailboxGUIApi.class);
if (api == null) {
    getLogger().warning("MailboxGUI API is unavailable; integration disabled.");
    return;
}
// MailboxGUIApiProvider.get() is an equivalent convenience lookup.

Use the Bukkit server thread for sends, item/economy access and notification mutations. These methods are synchronous and do not promise thread safety or async completion. If an HTTP/database task runs asynchronously, schedule its mail work back onto the server thread before calling the API.

Back to top ↑

Delivery requests

Recipients, lookup & policies

Recipient factory / builderMeaning
MailboxApiRecipient.of(uuid, name)Known UUID with a name; prefer stable validated identities.
MailboxApiRecipient.uuid(uuid)UUID-only recipient.
MailboxApiRecipient.name(name)Name-only lookup against available MailboxGUI data.
recipient(uuid, name) / recipient(uuid) / recipient(name)Add one recipient to a request.
recipients(list)Append explicit MailboxApiRecipient entries.
RecipientPolicyBehavior
KNOWN_MAILBOXGUI_PLAYERDefault: existing MailboxGUI data is sufficient; no physical registration is required.
REGISTERED_MAILBOX_ONLYExisting data AND a registered physical mailbox are required.
CREATE_IF_MISSINGMay create missing MailboxGUI data when a UUID is supplied. A name alone does not authorize manufacturing a new identity.
Known-recipient lookup and registration checks
var recipient = api.findRecipientByName("Alex");
if (recipient.isPresent()) {
    var uuid = recipient.get().getUuid();
    boolean hasData = api.hasMailboxData(uuid);
    boolean registered = api.hasRegisteredMailbox(uuid);
}

findRecipientByName returns Optional.empty for missing/blank names; it is not an external account lookup. A successful resolution does not guarantee successful serialization, economy access or delivery. Requests are evaluated per recipient; do not confuse isRegistered with data existence.

Back to top ↑

Delivery requests

Common request fields & defaults

Builder fieldMeaning
fromDisplayNameDisplay sender; blank/absent values use the relevant configured admin-server-name. Not proof of sender identity.
sourcePluginNameIntegration name for diagnostics. Do not put secrets or personal payloads here.
deliveryDelaySecondsDefault -1 means configured type delay; 0 means immediate; a positive value queues that many seconds.
notifyRecipientsDefault true; false suppresses the ordinary delivery notification route. It is not a deletion/ownership control.
recipientPolicyDefault KNOWN_MAILBOXGUI_PLAYER.
message / title / amount / contentsType-specific payload; validation still applies at send time.

Letter/book/money requests normalize text fields; package builders clone non-air ItemStacks and expose defensive content copies. Repeated recipient calls append recipients. contents(...) replaces the package contents list; do not confuse it with addItem(...).

Back to top ↑

Delivery requests

Send paper & book letters

sendLetter accepts LetterMailRequest. Paper messages must be nonblank and no longer than the archived API’s 256-character validation. sendBookLetter accepts BookLetterMailRequest with nonblank title and message; it does not impose the paper-letter 256-character check. Both need at least one recipient.

Paper letter example
var request = com.rismr1.mailboxgui.api.request.LetterMailRequest.builder()
    .recipient("Alex")
    .fromDisplayName("Quest Rewards")
    .message("Your quest reward is ready.")
    .sourcePluginName("ExampleAddon")
    .recipientPolicy(com.rismr1.mailboxgui.api.type.RecipientPolicy.KNOWN_MAILBOXGUI_PLAYER)
    .deliveryDelaySeconds(0)
    .notifyRecipients(true)
    .expiresAfter(java.time.Duration.ofDays(7))
    .build();
var result = api.sendLetter(request);
Book letter example
var book = com.rismr1.mailboxgui.api.request.BookLetterMailRequest.builder()
    .recipient("Alex")
    .fromDisplayName("Town Office")
    .title("Town Guide")
    .message("Welcome! Visit the town hall to begin.")
    .sourcePluginName("ExampleAddon")
    .deliveryDelaySeconds(0)
    .build();
var bookResult = api.sendBookLetter(book);

letter.enabled controls API letter/book delivery; disabled letters return DISABLED_BY_CONFIG. Use the exact version’s configuration rather than assuming the newer split letter controls apply.

Back to top ↑

Delivery requests

Send packages & experience

sendPackage accepts PackageMailRequest. Use addItem or contents for items and experienceAmount for raw XP. Capacity comes from getPackageContentLimit(): 7, 14 or 21 content positions depending on the configured rows. XP contributes one payload position when included.

Package and raw XP example
var reward = com.rismr1.mailboxgui.api.request.PackageMailRequest.builder()
    .recipient("Alex")
    .fromDisplayName("Quest Rewards")
    .addItem(new org.bukkit.inventory.ItemStack(org.bukkit.Material.DIAMOND, 2))
    .experienceAmount(100)
    .sourcePluginName("ExampleAddon")
    .deliveryDelaySeconds(0)
    .build();
var packageResult = api.sendPackage(reward);

Packages must not be empty. Null/air payloads are removed and item stacks are cloned. Nested MailboxGUI packages and blocked loaded shulkers fail validation. A package can be rejected before ANY recipient is delivered when its payload exceeds the limit or cannot serialize.

Custom item metadata is carried on ItemStacks; use the real server-supported item and its appropriate integration API. The public MailboxGUI API has no template-ID builder lookup or item-provider SPI in these versions. Templates are an administrator-command feature, not a request method you can invent.

Back to top ↑

Delivery requests

COD currency & return destinations

A PackageMailRequest with codAmount > 0 and/or codItemCurrencyContents is a COD package. Use addCodItemCurrency or codItemCurrencyContents for price items. Monetary prices need Vault/economy; item prices need the item-currency setting. Combined prices require both enabled routes.

CodReturnDestination.NONE is the default. SENDER needs a valid senderUuid. ADMIN_INBOX selects the Shared Admin Inbox; payment and declined/expired return switches must agree with that destination and the staff inbox must be enabled. Invalid combinations are reported, not silently converted.

Staff-inbox COD example — requires valid staff return setup
var cod = com.rismr1.mailboxgui.api.request.PackageMailRequest.builder()
    .recipient("Alex")
    .fromDisplayName("Server Shop")
    .addItem(new org.bukkit.inventory.ItemStack(org.bukkit.Material.DIAMOND, 2))
    .codAmount(50.0)
    .addCodItemCurrency(new org.bukkit.inventory.ItemStack(org.bukkit.Material.EMERALD, 5))
    .codReturnDestination(com.rismr1.mailboxgui.api.type.CodReturnDestination.ADMIN_INBOX)
    .returnCodPaymentToAdminInbox(true)
    .returnDeclinedOrExpiredToAdminInbox(true)
    .sourcePluginName("ExampleAddon")
    .deliveryDelaySeconds(0)
    .build();
var codResult = api.sendPackage(cod);

The item-currency price has its own capacity and safety checks. Reject nested packages/blocked nonempty shulkers in the price as well as the payload. Raw XP price items must be legitimate MailboxGUI-generated experience items; a renamed bottle is not an XP currency API. Validate the real server settings before treating a built request as deliverable.

Back to top ↑

Delivery requests

Send money mail

Server-created money reward
var money = com.rismr1.mailboxgui.api.request.MoneyMailRequest.builder()
    .recipient("Alex")
    .fromDisplayName("Event Rewards")
    .amount(125.50)
    .sourcePluginName("ExampleAddon")
    .deliveryDelaySeconds(0)
    .build();
var moneyResult = api.sendMoney(money);

sendMoney requires money.enabled, a positive amount and a working Vault economy provider. Pass finite, sensible amounts validated by your own integration. This is reward creation, not an automatic withdrawal from an addon account. Recipients claim the actual money mail through normal plugin handling.

Back to top ↑

Delivery requests

6.0.0 expiration & delivery identifiers

All four request builders support expirationDurationSeconds(long) and expiresAfter(Duration). Zero seconds means no expiration. A Duration must be positive and at least one whole second; negative values and arithmetic overflow are rejected. Validate external input before building a request.

Expiration begins at actual delivery. Queued requests retain the duration until arrival rather than consuming it while waiting. Immediate results can expose final mail IDs/expiration timestamps; queued results expose queue IDs and the stored expiration duration.

Optional delivery metadata after a send
for (var entry : result.getRecipientResults()) {
    if (entry.hasMailId()) getLogger().info("Committed mail ID: " + entry.getMailId());
    if (entry.hasQueueId()) getLogger().info("Queued delivery ID: " + entry.getQueueId());
    if (entry.hasExpiration()) {
        var expiresAt = java.time.Instant.ofEpochMilli(entry.getExpirationTimestampMillis());
    }
}
var deliveredIds = result.getDeliveredMailIds();
var queueIds = result.getQueuedDeliveryIds();
var recipientMailIds = result.getSuccessfulRecipientMailIds();
boolean anyExpiration = result.hasExpiringDeliveries();
Back to top ↑

Results & helpers

Results, failure handling & retries

Inspect the whole result, then each recipient
getLogger().info("Delivered=" + result.getDeliveredRecipients()
    + ", queued=" + result.getQueuedRecipients()
    + ", failed=" + result.getFailedRecipients());
for (var entry : result.getRecipientResults()) {
    if (!entry.isSuccessful()) {
        getLogger().warning("Mail outcome: " + entry.getStatus());
        // Store only needed, private operation state; do not leak player mail.
    }
}
for (var warning : result.getWarnings()) {
    getLogger().warning(warning);
}

MailboxSendResult contains the mail type, recipient results and warnings. getRequestedRecipients counts result entries, including validation-failure entries where appropriate. isSuccessful requires a nonempty result with every recipient successful. DELIVERED and QUEUED are successful statuses; a bulk request can have a mixture.

Documented statusMeaning
DELIVEREDMail committed to inbox.
QUEUEDAccepted for delayed delivery.
RECIPIENT_NOT_FOUNDNo resolvable recipient data.
NO_REGISTERED_MAILBOXPhysical-registration policy failed.
MAILBOX_DATA_MISSINGResolved identity has no usable data.
INVALID_REQUESTNull/empty/invalid request or required fields.
INBOX_WRITE_FAILEDInbox/queue write did not complete.
DISABLED_BY_CONFIGA required type/currency/XP setting is disabled.
ECONOMY_UNAVAILABLERequired Vault/provider route is unavailable.
TOO_MANY_CONTENTSPayload or COD currency exceeds capacity.
EMPTY_PACKAGENo usable contents/XP.
INVALID_EXPIRATIONInvalid expiration duration.
ADMIN_INBOX_DISABLEDStaff return inbox is unavailable.
INVALID_COD_RETURN_DESTINATIONReturn destination is invalid.
INVALID_COD_RETURN_CONFIGURATIONReturn switches/destination conflict.
NESTED_PACKAGE_BLOCKEDA MailboxGUI package was nested.
NON_EMPTY_SHULKER_BLOCKEDLoaded-shulker policy rejected contents.
SERIALIZATION_FAILEDMail item could not be serialized/created.
Back to top ↑

Results & helpers

Mailbox counts & notification helpers

MethodUse
hasMailboxData(uuid)Check stored player data separately from registration.
hasRegisteredMailbox(uuid)Check physical registration separately from inbox contents.
getUncheckedMailCount(uuid)Unchecked mail count, not total stored inventory occupancy.
getPendingLoginNotificationCount(uuid)Pending login-summary notifications.
hasPendingMailNotification(uuid)Whether notification state is pending.
refreshMailNotification(uuid)Ask the supported notification/visual route to refresh.
clearMailNotification(uuid)Clear notification state; does not delete the stored mail.
getPackageContentLimit()Running package capacity, not a hardcoded newest-version limit.

Helpers handle missing/null identities conservatively, but check a valid UUID yourself. Do not use notification clearing as a receipt, payment or authorization check. Directly rewriting plugin YAML/SQL bypasses validation and is not a supported API integration.

Back to top ↑

Events & reference

Delivery events & listener setup

MailboxMailDeliveredEvent describes an actual delivered item, with recipient/sender, origin, type, COD/money metadata, delayed flag and mass-delivery flag. MailboxMassMailDeliveredEvent aggregates a bulk delivery. Neither is a cancellable pre-send hook. Do not manually fire one to create mail.

Listener method inside a JavaPlugin implementing Listener
@org.bukkit.event.EventHandler
public void onMail(com.rismr1.mailboxgui.api.event.MailboxMailDeliveredEvent event) {
    if (event.isPartOfMassDelivery()) return; // Choose one bulk/single observation strategy.
    getLogger().info("Mail delivered: " + event.getDeliveryType());
}
Register your listener in onEnable()
getServer().getPluginManager().registerEvents(this, this);

Use getMailId/hasMailId and getExpirationTimestampMillis/hasExpiration where available on the event. The mass event also provides a successful-recipient mail-ID map and an expiration timestamp. Handle absent metadata instead of assuming every constructor or source supplies it.

Choose whether your addon processes individual events or the aggregate mass event; processing both as independent rewards double-counts bulk deliveries. Keep event work small and do not recursively send the same mail from its own handler.

Back to top ↑

Events & reference

Complete public signature reference

The expandable reference lists public method signatures and enum values read from this version’s API module. Request Builder methods are shown alongside request getters. These are signature references, not replacement Java source files; compile the authorized original module. Event/result constructors are omitted because integrations observe real delivery results/events rather than constructing them.

Dormant future-edition declarations are excluded from this local-release reference. Do not use a declaration in an archive as proof that an unreleased capability was provided.

Service discovery

MailboxGUIApi
MailboxGUIApi — 6.0.0 public signature reference
// MailboxGUIApi — public signatures (request Builder methods are included)
MailboxSendResult sendLetter(LetterMailRequest request);
MailboxSendResult sendBookLetter(BookLetterMailRequest request);
MailboxSendResult sendPackage(PackageMailRequest request);
MailboxSendResult sendMoney(MoneyMailRequest request);
Optional<MailboxApiRecipient> findRecipientByName(String playerName);
boolean hasMailboxData(UUID playerUuid);
boolean hasRegisteredMailbox(UUID playerUuid);
int getUncheckedMailCount(UUID playerUuid);
int getPendingLoginNotificationCount(UUID playerUuid);
boolean hasPendingMailNotification(UUID playerUuid);
boolean refreshMailNotification(UUID playerUuid);
boolean clearMailNotification(UUID playerUuid);
int getPackageContentLimit();
MailboxGUIApiProvider
MailboxGUIApiProvider — 6.0.0 public signature reference
// MailboxGUIApiProvider — public signatures (request Builder methods are included)
public static MailboxGUIApi get();

Requests

MailboxApiRecipient
MailboxApiRecipient — 6.0.0 public signature reference
// MailboxApiRecipient — public signatures (request Builder methods are included)
public static MailboxApiRecipient of(UUID uuid, String name);
public static MailboxApiRecipient uuid(UUID uuid);
public static MailboxApiRecipient name(String name);
public UUID getUuid();
public String getName();
public boolean hasUuid();
public boolean hasName();
LetterMailRequest
LetterMailRequest — 6.0.0 public signature reference
// LetterMailRequest — public signatures (request Builder methods are included)
public static Builder builder();
public List<MailboxApiRecipient> getRecipients();
public String getFromDisplayName();
public String getMessage();
public int getDeliveryDelaySeconds();
public boolean isNotifyRecipients();
public RecipientPolicy getRecipientPolicy();
public String getSourcePluginName();
public long getExpirationDurationSeconds();
public boolean hasExpiration();
public Builder recipient(UUID uuid, String name);
public Builder recipient(UUID uuid);
public Builder recipient(String name);
public Builder recipients(List<MailboxApiRecipient> recipients);
public Builder fromDisplayName(String fromDisplayName);
public Builder message(String message);
public Builder deliveryDelaySeconds(int deliveryDelaySeconds);
public Builder notifyRecipients(boolean notifyRecipients);
public Builder recipientPolicy(RecipientPolicy recipientPolicy);
public Builder sourcePluginName(String sourcePluginName);
public Builder expirationDurationSeconds(long seconds);
public Builder expiresAfter(Duration duration);
public LetterMailRequest build();
BookLetterMailRequest
BookLetterMailRequest — 6.0.0 public signature reference
// BookLetterMailRequest — public signatures (request Builder methods are included)
public static Builder builder();
public List<MailboxApiRecipient> getRecipients();
public String getFromDisplayName();
public String getTitle();
public String getMessage();
public int getDeliveryDelaySeconds();
public boolean isNotifyRecipients();
public RecipientPolicy getRecipientPolicy();
public String getSourcePluginName();
public long getExpirationDurationSeconds();
public boolean hasExpiration();
public Builder recipient(UUID uuid, String name);
public Builder recipient(UUID uuid);
public Builder recipient(String name);
public Builder recipients(List<MailboxApiRecipient> recipients);
public Builder fromDisplayName(String fromDisplayName);
public Builder title(String title);
public Builder message(String message);
public Builder deliveryDelaySeconds(int deliveryDelaySeconds);
public Builder notifyRecipients(boolean notifyRecipients);
public Builder recipientPolicy(RecipientPolicy recipientPolicy);
public Builder sourcePluginName(String sourcePluginName);
public Builder expirationDurationSeconds(long seconds);
public Builder expiresAfter(Duration duration);
public BookLetterMailRequest build();
PackageMailRequest
PackageMailRequest — 6.0.0 public signature reference
// PackageMailRequest — public signatures (request Builder methods are included)
public static Builder builder();
public List<MailboxApiRecipient> getRecipients();
public String getFromDisplayName();
public UUID getSenderUuid();
public List<ItemStack> getContents();
public int getExperienceAmount();
public double getCodAmount();
public List<ItemStack> getCodItemCurrencyContents();
public boolean hasCodItemCurrencyContents();
public boolean hasCodPrice();
public boolean isReturnCodPaymentToSender();
public CodReturnDestination getCodReturnDestination();
public boolean isReturnCodPaymentToAdminInbox();
public boolean isReturnDeclinedOrExpiredToAdminInbox();
public int getDeliveryDelaySeconds();
public boolean isNotifyRecipients();
public RecipientPolicy getRecipientPolicy();
public String getSourcePluginName();
public long getExpirationDurationSeconds();
public boolean hasExpiration();
public Builder recipient(UUID uuid, String name);
public Builder recipient(UUID uuid);
public Builder recipient(String name);
public Builder recipients(List<MailboxApiRecipient> recipients);
public Builder fromDisplayName(String fromDisplayName);
public Builder senderUuid(UUID senderUuid);
public Builder addItem(ItemStack item);
public Builder contents(List<ItemStack> contents);
public Builder experienceAmount(int experienceAmount);
public Builder codAmount(double codAmount);
public Builder addCodItemCurrency(ItemStack item);
public Builder codItemCurrencyContents(List<ItemStack> codItemCurrencyContents);
public Builder clearCodItemCurrencyContents();
public Builder returnCodPaymentToSender(boolean returnCodPaymentToSender);
public Builder codReturnDestination(CodReturnDestination destination);
public Builder returnCodPaymentToAdminInbox(boolean enabled);
public Builder returnDeclinedOrExpiredToAdminInbox(boolean enabled);
public Builder deliveryDelaySeconds(int deliveryDelaySeconds);
public Builder notifyRecipients(boolean notifyRecipients);
public Builder recipientPolicy(RecipientPolicy recipientPolicy);
public Builder sourcePluginName(String sourcePluginName);
public Builder expirationDurationSeconds(long seconds);
public Builder expiresAfter(Duration duration);
public PackageMailRequest build();
MoneyMailRequest
MoneyMailRequest — 6.0.0 public signature reference
// MoneyMailRequest — public signatures (request Builder methods are included)
public static Builder builder();
public List<MailboxApiRecipient> getRecipients();
public String getFromDisplayName();
public double getAmount();
public int getDeliveryDelaySeconds();
public boolean isNotifyRecipients();
public RecipientPolicy getRecipientPolicy();
public String getSourcePluginName();
public long getExpirationDurationSeconds();
public boolean hasExpiration();
public Builder recipient(UUID uuid, String name);
public Builder recipient(UUID uuid);
public Builder recipient(String name);
public Builder recipients(List<MailboxApiRecipient> recipients);
public Builder fromDisplayName(String fromDisplayName);
public Builder amount(double amount);
public Builder deliveryDelaySeconds(int deliveryDelaySeconds);
public Builder notifyRecipients(boolean notifyRecipients);
public Builder recipientPolicy(RecipientPolicy recipientPolicy);
public Builder sourcePluginName(String sourcePluginName);
public Builder expirationDurationSeconds(long seconds);
public Builder expiresAfter(Duration duration);
public MoneyMailRequest build();

Results

MailboxSendResult
MailboxSendResult — 6.0.0 public signature reference
// MailboxSendResult — public signatures (request Builder methods are included)
public static MailboxSendResult singleFailure(MailType mailType, RecipientStatus status, String message);
public MailType getMailType();
public List<MailboxRecipientResult> getRecipientResults();
public List<String> getWarnings();
public boolean isSuccessful();
public int getRequestedRecipients();
public int getDeliveredRecipients();
public int getQueuedRecipients();
public int getFailedRecipients();
public List<String> getDeliveredMailIds();
public List<String> getQueuedDeliveryIds();
public boolean hasExpiringDeliveries();
public Map<UUID, String> getSuccessfulRecipientMailIds();
MailboxRecipientResult
MailboxRecipientResult — 6.0.0 public signature reference
// MailboxRecipientResult — public signatures (request Builder methods are included)
public UUID getRecipientUuid();
public String getRecipientName();
public RecipientStatus getStatus();
public String getMessage();
public String getMailId();
public boolean hasMailId();
public long getExpirationTimestampMillis();
public boolean hasExpiration();
public String getQueueId();
public boolean hasQueueId();
public long getExpirationDurationSeconds();
public boolean isSuccessful();
RecipientStatus
RecipientStatus — 6.0.0 public signature reference
enum RecipientStatus {
  DELIVERED,
  QUEUED,
  RECIPIENT_NOT_FOUND,
  NO_REGISTERED_MAILBOX,
  MAILBOX_DATA_MISSING,
  INVALID_REQUEST,
  INBOX_WRITE_FAILED,
  DISABLED_BY_CONFIG,
  ECONOMY_UNAVAILABLE,
  TOO_MANY_CONTENTS,
  EMPTY_PACKAGE,
  INVALID_EXPIRATION,
  ADMIN_INBOX_DISABLED,
  INVALID_COD_RETURN_DESTINATION,
  INVALID_COD_RETURN_CONFIGURATION,
  NESTED_PACKAGE_BLOCKED,
  NON_EMPTY_SHULKER_BLOCKED,
  SERIALIZATION_FAILED
}

Policies and delivery types

RecipientPolicy
RecipientPolicy — 6.0.0 public signature reference
enum RecipientPolicy {
  REGISTERED_MAILBOX_ONLY,
  KNOWN_MAILBOXGUI_PLAYER,
  CREATE_IF_MISSING
}
MailType
MailType — 6.0.0 public signature reference
enum MailType {
  LETTER,
  PACKAGE,
  MONEY
}
MailDeliveryType
MailDeliveryType — 6.0.0 public signature reference
enum MailDeliveryType {
  LETTER,
  BOOK_LETTER,
  PACKAGE,
  COD_PACKAGE,
  RETURNED_COD_PACKAGE,
  COD_ITEM_CURRENCY_PAYMENT,
  MONEY_MAIL
}
MailDeliveryOrigin
MailDeliveryOrigin — 6.0.0 public signature reference
enum MailDeliveryOrigin {
  PLAYER,
  ADMIN,
  API,
  SYSTEM
}
MailDeliveryScope
MailDeliveryScope — 6.0.0 public signature reference
enum MailDeliveryScope {
  SINGLE_SERVER
}
MailDeliverySource
MailDeliverySource — 6.0.0 public signature reference
enum MailDeliverySource {
  LOCAL_DELIVERY,
  PLAYER_ACTION,
  ADMIN_COMMAND,
  API,
  DELAYED_QUEUE,
  SYSTEM
}
CodReturnDestination
CodReturnDestination — 6.0.0 public signature reference
enum CodReturnDestination {
  NONE,
  SENDER,
  ADMIN_INBOX
}

Delivery events

MailboxMailDeliveredEvent
MailboxMailDeliveredEvent — 6.0.0 public signature reference
// MailboxMailDeliveredEvent — public signatures (request Builder methods are included)
public UUID getRecipientUuid();
public String getRecipientName();
public UUID getSenderUuid();
public String getSenderName();
public MailDeliveryOrigin getOrigin();
public MailDeliveryType getDeliveryType();
public double getCodPrice();
public String getCodPriceText();
public double getMoneyAmount();
public boolean isDelayedDelivery();
public boolean isPartOfMassDelivery();
public String getEventId();
public String getMailId();
public boolean hasMailId();
public MailDeliveryScope getDeliveryScope();
public MailDeliverySource getDeliverySource();
public long getExpirationTimestampMillis();
public boolean hasExpiration();
public boolean isAdminMail();
public boolean isPlayerMail();
public boolean isApiMail();
public boolean hasSenderUuid();
public boolean hasCodPrice();
public boolean hasCodPriceText();
public boolean hasMoneyAmount();
public HandlerList getHandlers();
public static HandlerList getHandlerList();
MailboxMassMailDeliveredEvent
MailboxMassMailDeliveredEvent — 6.0.0 public signature reference
// MailboxMassMailDeliveredEvent — public signatures (request Builder methods are included)
public UUID getSenderUuid();
public String getSenderName();
public MailDeliveryOrigin getOrigin();
public MailDeliveryType getDeliveryType();
public int getRequestedRecipientCount();
public int getSuccessfulRecipientCount();
public int getFailedRecipientCount();
public double getCodPrice();
public String getCodPriceText();
public double getMoneyAmount();
public boolean isDelayedDelivery();
public List<UUID> getSuccessfulRecipientUuids();
public String getEventId();
public MailDeliveryScope getDeliveryScope();
public MailDeliverySource getDeliverySource();
public long getExpirationTimestampMillis();
public boolean hasExpiration();
public Map<UUID, String> getSuccessfulRecipientMailIds();
public boolean isAdminMail();
public boolean isApiMail();
public boolean hasSenderUuid();
public boolean hasCodPrice();
public boolean hasCodPriceText();
public boolean hasMoneyAmount();
public HandlerList getHandlers();
public static HandlerList getHandlerList();
Back to top ↑

Help

Integration checks & support

ProblemCheck
Dependency cannot resolveCompile/install the matching archived API and parent locally; it was never on Maven Central.
ClassNotFoundException / no serviceprovided dependency, matching installed jar, dependency load order and API class identity.
No recipientCorrect UUID/name, real stored data and chosen RecipientPolicy.
Package rejectedPayload/XP capacity, nested items, loaded-shulker policy and usable serialization.
Money/COD unavailableRequired provider/toggles, amount and return setup.
Queued mail not yet visibleDelay processing and actual delivery events; QUEUED is not delivered.
Duplicate rewardOwn transaction bookkeeping, partial-result retry strategy and single-versus-mass event handling.
  1. Build your addon against the exact archived module.
  2. Test on a disposable server with matching MailboxGUI and hooks.
  3. Verify a known recipient, a missing one and both data/registration policies.
  4. Test immediate and delayed paper/book/package/money, then COD and deliberate validation failures.
  5. Confirm notification toggles, partial outcomes and event handling do not duplicate rewards.
ImagineCraft plugin Discord supportBack to the 6.0.0 wiki
Back to top ↑