Mailbox¶
The mailbox stores messages for the current player. Use Balancy.API.Mailbox to load messages, read their contents, update their status, and delete them. Messages can contain custom JSON or text (Raw), or a Nutaku Daily Reward Calendar reward ID (NutakuDailyReward).
Your game controls the mailbox UI and decides when and how to handle each message.
Reward handling
Mailbox methods do not grant items or change the player's game save. Your game must apply the reward, save the result, and then mark the message as processed.
Getting Started¶
Call mailbox methods after initializing Balancy and completing player authentication. Requests use the current player's account, game, and environment automatically.
The examples below use the Unity SDK (C#). Import these namespaces:
using Balancy;
using Balancy.Mail;
using UnityEngine;
Available Methods¶
All methods are asynchronous and return a MailboxResponse through a callback. Always check Success before using the result.
| Method | Description |
|---|---|
GetMessages(callback) |
Load the first page with the default limit of 50 messages. |
GetMessages(options, callback) |
Load a page using MailboxListOptions. |
GetMessage(messageId, callback) |
Load a single message by its Id. |
MarkRead(messageId, callback) |
Mark a message as read. |
MarkProcessed(messageId, callback) |
Record that your game has handled the message. |
Delete(messageId, callback) |
Remove a message from the player's mailbox. |
Sync(callback) |
Ask the server to deliver pending rewards to the current player's mailbox. |
Get Messages¶
Use GetMessages to load messages that have already been delivered. The server returns them from newest to oldest, including unread, read, and processed messages. Deleted messages are excluded.
private string _nextCursor;
public void LoadMessages(string cursor = null)
{
var options = new MailboxListOptions
{
Limit = 20,
Cursor = cursor
};
API.Mailbox.GetMessages(options, page =>
{
if (!page.Success)
{
Debug.LogError($"Mailbox error: {page.ErrorCode} => {page.ErrorMessage}");
return;
}
_nextCursor = page.NextCursor;
Debug.Log($"Unread messages: {page.UnreadCount}");
if (page.InvalidMessageCount > 0)
Debug.LogWarning($"Skipped invalid messages: {page.InvalidMessageCount}");
foreach (var message in page.Messages)
{
Debug.Log($"Message {message.Id}: {message.Type}, {message.Status}");
// Add the message to your UI. See Message Types below to read its contents.
}
});
}
public void LoadNextPage()
{
if (!string.IsNullOrEmpty(_nextCursor))
LoadMessages(_nextCursor);
}
Call LoadMessages() to load or refresh the first page, and LoadNextPage() when the player requests more messages. Replace the displayed list when refreshing and append messages when loading the next page. Reset the displayed list and cursor after switching accounts.
Pagination¶
| Option | Description |
|---|---|
Limit |
Maximum number of messages per page. Default: 50. Allowed range: 1–100. |
Cursor |
The previous response's NextCursor. Leave it unset for the first page. |
The cursor is an opaque string: pass it back unchanged. It is not a page number or an offset. A null or empty NextCursor means there are no more pages. Use NextCursor to decide whether to continue, even if some messages were skipped by the parser.
List Response¶
| Property | Description |
|---|---|
Messages |
Successfully parsed messages on this page. |
NextCursor |
Cursor for the next page, or null when this is the last page. |
UnreadCount |
Total unread messages in the mailbox, across all pages. |
ServerTime |
Server timestamp as a UTC ISO 8601 string. |
InvalidMessageCount |
Messages on this page omitted because their common fields could not be parsed. |
Message Types¶
The SDK selects a message class using its type and payload version. All messages inherit from MailMessage.
| Type | Numeric Value | C# Class | Content |
|---|---|---|---|
MailMessageType.Raw |
0 |
RawMailMessage |
Custom JSON or a string. |
MailMessageType.NutakuDailyReward |
1 |
NutakuDailyRewardMessage |
A RewardId identifying the reward in your game. |
Type and Status are numbers in API responses and enums in the SDK. The current payload version is 1.
Common Properties¶
| Property | Description |
|---|---|
Id |
Unique message ID. Use it in mailbox methods and to track messages your game has handled. |
Type |
Original message type as MailMessageType. |
Kind |
The parsed class as MailMessageKind. May differ from Type for a fallback message. |
Status |
Current MailMessageStatus: Unread, Read, or Processed. |
PayloadVersion |
Version of the payload format. |
PayloadJson |
Payload serialized as JSON, available for every message type. |
ParseStatus |
Parsed, UnsupportedType, UnsupportedVersion, or InvalidPayload. |
CreatedAt |
Creation timestamp as a UTC ISO 8601 string. |
ReadAt |
Timestamp when first marked as read, or null. |
ProcessedAt |
Timestamp when first marked as processed, or null. |
Use the parsed class to access the message contents:
private void ShowMessage(MailMessage message)
{
if (message.ParseStatus != MailParseStatus.Parsed)
{
Debug.LogWarning($"Cannot handle message {message.Id}: {message.ParseStatus}");
return; // Keep the message available for a compatible handler.
}
if (message is NutakuDailyRewardMessage dailyReward)
{
Debug.Log($"Nutaku reward: {dailyReward.RewardId}");
// Resolve RewardId using your game's reward definitions and show a claim button.
}
else if (message is RawMailMessage raw)
{
if (raw.TryGetText(out var text))
Debug.Log(text);
else
Debug.Log(raw.PayloadJson); // Parse this using your own payload schema.
}
}
Raw Messages¶
A RawMailMessage can contain a JSON object, array, or other JSON value, including a string. TryGetText(out var text) returns true only when the payload itself is a string; it returns the decoded text without JSON quotes. For other payloads, parse PayloadJson using a JSON parser and your own data model.
For example, if your game's raw payload format is {"title":"Welcome","coins":100}, you can parse it with Unity's JsonUtility:
[System.Serializable]
public class CustomMailPayload
{
public string title;
public int coins;
}
private void ShowCustomMessage(RawMailMessage message)
{
if (message.ParseStatus != MailParseStatus.Parsed)
return;
// Use this handler only for messages following the object schema above.
var payload = JsonUtility.FromJson<CustomMailPayload>(message.PayloadJson);
Debug.Log($"{payload.title}: {payload.coins} coins");
// Display the contents. Your game decides whether and when to grant anything.
}
Nutaku Daily Rewards¶
After a player claims an in-game reward on Nutaku's Daily Reward Calendar, Balancy stores the event and delivers a NutakuDailyRewardMessage to the player's mailbox. If the player has never played your game, the reward remains pending until their Nutaku identity is associated with an authenticated Balancy account. See Nutaku setup for the Benefits Notification URL.
NutakuDailyRewardMessage.RewardId is the reward ID configured for the Nutaku campaign. Resolve it using your own reward definitions; the message does not contain an inventory item or an amount to grant automatically.
A recommended claim flow:
- Check the message status and your saved record of handled message IDs. A processed message should not be granted again.
- For an unhandled message, resolve
RewardIdand grant the corresponding reward in your game. - Save the reward changes and the handled
message.Idtogether in the player's game save. - After saving succeeds, call
MarkProcessed(message.Id, callback)as shown below. - If marking the message fails, retry it later. When its ID is already in the saved record, repeat only
MarkProcessed, without granting the reward again.
Leave unknown reward IDs unprocessed so the game can handle them after its reward definitions are updated. Rewards should be usable at any progression level, including by new players.
Balancy deduplicates repeated Nutaku notifications for the same game, environment, title, user, and reward ID. This prevents duplicate letters; your game must also prevent duplicate grants when retrying a claim. Use your save system's conflict and concurrency controls when the same account can be used on multiple devices.
Unsupported Messages¶
An unknown message type, unsupported payload version, or invalid typed payload is returned as RawMailMessage. It preserves Type, PayloadVersion, and PayloadJson, with the reason in ParseStatus. Check ParseStatus before treating a raw message as your own custom format.
If the common message fields themselves are invalid, the SDK skips that message and increments InvalidMessageCount. A successful list response can therefore contain fewer messages than the server returned. An invalid single-message response fails instead.
Get a Single Message¶
Use GetMessage when you already have a message ID. The result is available through response.Message.
public void LoadMessage(string messageId)
{
API.Mailbox.GetMessage(messageId, response =>
{
if (!response.Success)
{
Debug.LogError($"GetMessage failed: {response.ErrorCode} => {response.ErrorMessage}");
return;
}
ShowMessage(response.Message);
});
}
Message Status¶
| Status | Numeric Value | Meaning |
|---|---|---|
MailMessageStatus.Unread |
0 |
The message has not been marked as read. |
MailMessageStatus.Read |
1 |
The message has been read but not processed. |
MailMessageStatus.Processed |
2 |
Your game has confirmed that it handled the message. |
Loading a message does not change its status. Call MarkRead when the player opens it:
public void MarkMessageRead(string messageId)
{
API.Mailbox.MarkRead(messageId, response =>
{
if (!response.Success)
{
Debug.LogError($"MarkRead failed: {response.ErrorCode} => {response.ErrorMessage}");
return;
}
Debug.Log($"Message status: {response.Message.Status}");
// Update your UI with response.Message.
});
}
Call MarkProcessed after your game has completed its handling of the message. For rewards, call this only after the reward and handled message ID have been saved successfully:
public void ConfirmMessageProcessed(string messageId)
{
API.Mailbox.MarkProcessed(messageId, response =>
{
if (!response.Success)
{
Debug.LogError($"MarkProcessed failed: {response.ErrorCode} => {response.ErrorMessage}");
return; // Retry this confirmation later; do not grant the reward again.
}
Debug.Log($"Message status: {response.Message.Status}");
// Update your UI with response.Message.
});
}
Status changes only move forward. MarkProcessed can be called on an unread message and also sets its read timestamp. Calling MarkRead on an already processed message leaves it processed. There is no method to reset a message to unread.
MarkRead and MarkProcessed return the updated message. Previously loaded message objects are not updated automatically; use the returned object or reload the list.
Delete a Message¶
Delete removes a message from subsequent mailbox reads. It works with any status, so your UI should decide when deletion is appropriate.
public void DeleteMessage(string messageId)
{
API.Mailbox.Delete(messageId, response =>
{
if (!response.Success)
{
Debug.LogError($"Delete failed: {response.ErrorCode} => {response.ErrorMessage}");
return;
}
Debug.Log($"Deleted message: {messageId}");
// Remove it from your UI. Reload the list to refresh UnreadCount.
});
}
Deletion does not grant or undo a reward. Repeated Nutaku notifications do not recreate a deleted reward message. A successful delete response has no Message.
Sync Pending Rewards¶
The server attempts delivery when a Nutaku notification arrives and when the player authenticates. Use Sync to request another delivery attempt for the current player, for example before refreshing the mailbox after login or returning from Nutaku.
Sync delivers pending rewards as messages. It does not grant their contents, mark them as processed, or return the message list. Use GetMessages afterwards to read the mailbox.
public void SyncAndLoadMessages()
{
API.Mailbox.Sync(response =>
{
if (!response.Success)
{
Debug.LogError($"Sync failed: {response.ErrorCode} => {response.ErrorMessage}");
return;
}
Debug.Log($"Newly delivered messages: {response.DeliveredCount}");
LoadMessages();
if (response.HasMore)
{
// Schedule another Sync in your refresh flow to deliver the next batch.
}
});
}
DeliveredCount is the number of messages created by this sync call. HasMore indicates that another delivery batch may be needed. Continue syncing when it is true, and stop or retry later on failure. HasMore belongs to sync; use NextCursor for message list pagination.
The SDK does not poll for new messages or provide a mailbox UI. Call these methods from your game's UI and refresh flow.
Troubleshooting¶
| Result | What to Check |
|---|---|
Success == false |
Inspect ErrorCode and ErrorMessage. Do not interpret an empty Messages list on a failed request as an empty mailbox. |
InvalidMessageCount > 0 |
Some messages have invalid common fields. Check the response format and SDK version; message types and statuses must be numeric. |
A RawMailMessage has ParseStatus != Parsed |
This is a fallback for an unsupported or invalid typed message. Inspect its original Type, PayloadVersion, and PayloadJson. |
| A Nutaku reward has not appeared | Check the current account and environment, completed Nutaku authentication, and the Benefits Notification URL configuration. Call Sync, then GetMessages. |
UnreadCount counts the server's unread messages before client parsing and across all pages. It can be greater than Messages.Count, including when invalid messages were skipped.