OnItemSubmit
OnItemSubmit is called once for each item in a mailbox's input container while the mailbox moves those items into the owner's inventory. Returning a non-null value keeps that item in the input slot.
object OnItemSubmit(Item slot, Mailbox mailbox, BasePlayer fromPlayer)Parameters
| Parameter | Type | Description |
|---|---|---|
slot | Item | The Item currently sitting in one of the mailbox's input slots. It is the exact item object that would be moved into the mailbox owner's inventory. |
mailbox | Mailbox | The Mailbox entity whose SubmitInputItems loop is running. Use it to check the owner, position, or call PlayerIsOwner. |
fromPlayer | BasePlayer | The BasePlayer who submitted the items, or null when the submission did not come from a player context. Null-check it before reading any player data. |
Return value
Return null to allow the item to be moved into the mailbox owner's inventory, which also plays the drop sound and applies the sender rules. Return any non-null object to skip the move for that item, leaving it in the input slot; because SubmitInputItems returns void, the returned value itself is not used.
How it works
Mailbox.SubmitInputItems iterates every slot of the mailbox's input container and calls this hook for each non-empty slot before attempting to move the item. Each call passes the item being submitted, the mailbox entity, and the player who triggered the submission (which can be null). Returning a value from the hook short-circuits the loop body for that item: the game skips MoveToContainer and the drop sound, and the item stays in the input slot. Returning null is the only way to let the item through, so there is no way to modify the item through the return value — only allow or block it.
Because it fires per item, a full input container produces several calls in one submit. Declaring fromPlayer as a more specific type such as BasePlayer does not narrow anything here since that is already the declared type; the only way to narrow is logically, by letting every item through that fails your check. Note that blocking a submission does not refill the mailbox timer or refund the item — the item simply remains in the input slot, and a later submit will call the hook again.
Example plugin: Block mailbox submissions from players outside the owner's team
using UnityEngine;
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
namespace Oxide.Plugins
{
[Info("Mailbox Submit Guard", "RustPluginGenerator", "1.0.0")]
[Description("Restricts who can submit items into a mailbox, with a chat warning for blocked attempts.")]
public class MailboxSubmitGuard : RustPlugin
{
private const string PermBypass = "mailboxsubmitguard.bypass";
private PluginConfig config;
private readonly Dictionary<ulong, float> lastWarn = new Dictionary<ulong, float>();
private class PluginConfig
{
[JsonProperty("Only allow owner's team")]
public bool TeamOnly { get; set; } = true;
[JsonProperty("Block all mailbox submissions")]
public bool BlockAll { get; set; } = false;
[JsonProperty("Warning cooldown (seconds)")]
public float WarnCooldown { get; set; } = 10f;
}
protected override void LoadDefaultConfig() => config = new PluginConfig();
protected override void LoadConfig()
{
base.LoadConfig();
try
{
config = Config.ReadObject<PluginConfig>();
if (config == null) throw new Exception();
}
catch
{
PrintWarning("Configuration file is invalid, using defaults");
LoadDefaultConfig();
}
SaveConfig();
}
protected override void SaveConfig() => Config.WriteObject(config);
protected override void LoadDefaultMessages()
{
lang.RegisterMessages(new Dictionary<string, string>
{
["NotAllowed"] = "You are not allowed to submit items to this mailbox.",
["Disabled"] = "Mailbox submissions are currently disabled."
}, this);
}
private string Msg(string key, string userId = null, params object[] args) =>
string.Format(lang.GetMessage(key, this, userId), args);
private void Init()
{
permission.RegisterPermission(PermBypass, this);
}
private object OnItemSubmit(Item slot, Mailbox mailbox, BasePlayer fromPlayer)
{
if (slot == null || mailbox == null) return null;
if (config.BlockAll)
{
Warn(fromPlayer, "Disabled");
return false;
}
if (!config.TeamOnly || fromPlayer == null) return null;
if (fromPlayer.UserIDString == mailbox.OwnerID.ToString()) return null;
if (permission.UserHasPermission(fromPlayer.UserIDString, PermBypass)) return null;
if (fromPlayer.currentTeam != 0 && fromPlayer.currentTeam == mailbox.OwnerID)
return null;
Warn(fromPlayer, "NotAllowed");
return false;
}
private void Warn(BasePlayer player, string key)
{
if (player == null || !player.IsConnected) return;
float now = UnityEngine.Time.realtimeSinceStartup;
float last;
if (lastWarn.TryGetValue(player.userID, out last) && now - last < config.WarnCooldown) return;
lastWarn[player.userID] = now;
player.ChatMessage(Msg(key, player.UserIDString));
}
private void Unload()
{
lastWarn.Clear();
}
}
}The plugin listens on OnItemSubmit and, when the config enables the restriction, compares the submitting player's team with the mailbox owner's team. Owners are always allowed. Players on a different team (or with no team) cause the hook to return false, which keeps the item in the input slot instead of moving it into the owner's inventory. A lang message with a cooldown per player explains why the submission was refused, so a player mashing the submit button does not get spammed. Every parameter is null-checked, and the owner check uses the mailbox's OwnerID converted to a user ID string for comparison.
Common use cases
Team-only delivery
Only allow team members to drop items into a teammate's mailbox, keeping random players from filling a base's mailbox with junk.
Filter submitted items
Reject items of a certain category (for example explosives or tools) by returning a non-null value for those slots and sending a short warning to the submitter.
Server-wide mailbox restrictions
Use the config flags to disable mailbox submissions entirely on PvE-style servers or during events, without having to patch or remove the mailbox entity.
Pitfalls
fromPlayer can be null
The submission may not come from a player, so always null-check fromPlayer before reading UserIDString or currentTeam.
Blocked items stay in the slot
Returning a value does not delete or drop the item; it remains in the mailbox input container and will trigger the hook again on the next submit attempt.
One call per item
A full input container produces multiple calls in a single submit, so keep the hook cheap and cache derived data instead of querying teams repeatedly if the plugin grows.
Build a plugin with OnItemSubmit
Describe what should happen and get a compiled plugin that uses this hook.
Edit the prompt on the next screen. 2 free plugins a month, no card.
Last updated Oct 26, 2026. Found a mistake? Email support@rustplugingenerator.com.
Build a plugin with OnItemSubmit
Generate