# Team Mailbox

**URL:** https://heroiclabs.com/docs/hiro/concepts/teams/mailbox/
**Keywords:** team mailbox, hiro
**Categories:** hiro, mailbox, teams

---


# Team Mailbox

## Overview

The Team Mailbox provides a structured and controlled mechanism for managing delayed or batch-distributed rewards. Admins can strategically grant, claim, and manage rewards, promoting effective reward distribution and management within the team.

## Key Operations

The Team Mailbox allows admins to control reward distribution with clear visibility and management options. It supports:

- Granting new rewards.
- Claiming and optionally deleting rewards.
- Managing mailbox entries with automated expiry and size controls.

### MailboxGrant

- Adds rewards to the mailbox.
- Automatically timestamps rewards.
- Applies expiry rules and maintains size limits.
- Employs FIFO (First-In-First-Out) trimming when limits are exceeded.

### MailboxList

- Lists all active and unclaimed rewards.
- Supports pagination using cursors.
- Accessible by all team members for transparency.

### MailboxClaim (Admins only)

- Allows admins to claim selected rewards.
- Claimed rewards can be retained (for tracking) or removed from the mailbox.
- Integrates claimed rewards into systems like Wallet or Inventory.
- Allows customization through hooks to define specific reward behaviors.

### MailboxDelete (Admins only)

- Removes mailbox entries.
- Useful for moderation, duplicate handling, or routine maintenance.

## Example Implementation

### Level Progression Rewards (Team RPG Scenario)

When a team reaches a significant milestone (e.g., collectively achieving level 20):

- Rewards (premium currency, special gear, energy boosts) are added to the mailbox.
- Admins review and claim rewards, integrating them strategically.
- Expired or irrelevant rewards can be cleaned to maintain efficiency.

This scenario illustrates how the mailbox supports strategic reward distribution aligned with team progress.

## Key Terms

- **Mailbox Entry:** Individual reward records with metadata, expiry, and status.
- **FIFO Trimming:** Automatic removal of the oldest entries when mailbox limits are exceeded.
- **Reward Hooks:** Customizable logic executed during reward claiming for automation or conditional behavior.
- **Expiry Logic:** Configurable time-based expiry rules (ExpirySec) for mailbox rewards.

## Important Sub-concepts

### Expiry & Size Limits

- **ExpirySec:** Time-based rules controlling mailbox entry expiration.
- **MaxSize:** Configurable limit of mailbox entries, with automated removal of oldest entries when exceeded.

## Technical Considerations

### Reward Availability

- All player-level reward types are also supported at the team level.

### Reward Distribution

- Rewards require explicit claiming by admins.
- No default automated distribution; however, customizable hooks allow for automation.

### Interaction with Other Systems

- Further definition is needed regarding interactions with related systems such as Team Inventory, Leaderboards, and Achievements.