Get sent mail

Use GetSentMailsAsync() and GetMailAsync() to retrieve the sent mail list and the details of a single sent mail item. Use list retrieval to check the overall status of sent mail, and use detail retrieval to check the latest status of a specific mail item.

Prepare for retrieval

Sent mail retrieval is divided into list retrieval and single-item detail retrieval. For list retrieval, prepare the filter conditions; for single-item detail retrieval, prepare the MailId you saved when sending.

Prepare the list retrieval conditions

Retrieve the list by combining category, content type, status, and pagination conditions in GetSentMailsRequest. To check the history of operational mail periodically, we recommend using MailStatus and MailContentType together to retrieve only the mail you need.

• MailCategory: Mailbox category to retrieve. If omitted, only the default "DEFAULT" category is retrieved
• MailContentType: Content type filter. Text or Attachment. If omitted, no content type condition is applied
• MailStatus: Status filter. Active, Revoked, Expired. If omitted, no status condition is applied
• Cursor, Size: Reference point for the next page and page size

MailId for single-item retrieval

For GetMailAsync(), use the MailId you saved when sending. To check again whether the mail has been recalled or has expired, retrieve the details of that mail again with the same MailId.

Sent mail status values

Check the sent mail status with SentMailListItem.MailStatus in the list response and MailResponseData.MailStatus in the detail response.

• Active: Valid mail
• Revoked: Recalled mail
• Expired: Expired mail

The sent mail list retrieval includes not only valid (Active) mail but also recalled (Revoked) mail and expired (Expired) mail so that you can check the sending history. If you specify MailStatus, only mail with that status is retrieved; if you omit it, all mail is retrieved regardless of status. Only deleted sent mail is excluded from the sent mail list results.

Get the sent mail list

GetSentMailsAsync

Call GetSentMailsAsync() to get the list of sent mail that matches the retrieval conditions and the pagination information. Use it to check the overall mail status or the sending history. To keep tracking the list of operational mail, use Data.Meta.Page.HasNext and NextCursor in the response to continue retrieving the next page.

Call parameters

Field name	Type	Required	Description
request	GetSentMailsRequest	Required	Sent mail list retrieval conditions
context	ApiCallContext?	Optional	Per-call settings object. If omitted, the default values are used.

GetSentMailsRequest

Field name	Type	Required	Description
MailCategory	string	Optional	Mailbox category to retrieve. Default "DEFAULT", up to 64 characters
MailContentType	SentMailSearchRequestMailContentType?	Optional	Content type filter. Text, Attachment
MailStatus	SentMailSearchRequestMailStatus?	Optional	Status filter. Active, Revoked, Expired
Cursor	string?	Optional	Reference point for the next page. NextCursor of the previous response
Size	int	Optional	Number of items to get at a time. Minimum 1, maximum 50, default 10

Call example

See the example below and the response status for the success result of MailboxGetSentMailsResult and the domain-specific results (Outcome) of this method. For the result model and handling principles of common failures (Failure) returned when the request cannot be performed, see Common error handling.

Unity

using Hive.Axyl.Mailbox;
using Hive.Axyl.Core;

IMailboxService mailbox = HiveCore.Resolve<IMailboxService>();

var result = await mailbox.GetSentMailsAsync(new GetSentMailsRequest {
    MailStatus = SentMailSearchRequestMailStatus.Active,
    Size       = 20,
});

switch (result)
{
    case MailboxGetSentMailsResult.Success success:
        foreach (SentMailListItem item in success.Data.Items)
            Debug.Log($"{item.MailId} {item.Title} ({item.MailStatus})");
        break;

    case MailboxGetSentMailsResult.Failure failure:
        HiveError err = failure.Problem;
        Debug.LogError($"[{err.Code}] {err.Message} (trace: {err.TraceId})");
        break;

    default:
        Debug.LogWarning($"Unhandled result: {result.GetType().Name}");
        break;
}

Response data

On success, the result is contained in Data (SentMailListResponseData) of MailboxGetSentMailsResult.Success. The list is in Data.Items, and the pagination information is in Data.Meta.

Field name	Type	Required	Description
Data.Items	IReadOnlyList<SentMailListItem>	Required	List of the retrieved sent mail. Empty list if no mail matches the conditions
Data.Meta	MetaPage?	Optional	Pagination information

SentMailListItem

SentMailListItem is each item of Data.Items. All fields are declared with types that can hold null, so check whether a value is null before you show it on the screen or pass it to the next call.

Field name	Type	Required	Description
MailId	string?	Optional	Sent mail identifier
Title	string?	Optional	Mail title
SenderDisplayName	string?	Optional	Sender name shown on the mail screen
MailStatus	SentMailListItemMailStatus?	Optional	Sent mail status. Active, Revoked, Expired
MailCategory	string?	Optional	Mailbox category
MailContentType	SentMailListItemMailContentType?	Optional	Mail content type. Text, Attachment
ExpiresAt	DateTimeOffset?	Optional	Mail expiration time
CreatedAt	DateTimeOffset?	Optional	Mail creation time
ClosedAt	DateTimeOffset?	Optional	Mail close time. The UTC time when the mail status changed to Expired or Revoked. null in the Active status
RecipientCount	long?	Optional	Number of recipients. The total number of users who received the mail
FirstRecipientPlayerId	long?	Optional	First Player ID in the recipient list. Summary information for showing the sent mail list. Check the full recipient list with single mail detail retrieval. null for mail sent to all users
SenderId	string?	Optional	Sender identifier

MetaPage

Data.Meta contains the cursor information used for page navigation.

Field name	Type	Required	Description
Page	AxylCursorPagination?	Optional	Cursor page information
Page.HasNext	bool?	Optional	Whether a next page exists
Page.NextCursor	string?	Optional	Cursor value used to retrieve the next page

Page also has HasPrevious and PreviousCursor for the previous page, but sent mail list retrieval does not support moving to the previous page, so these two values are always null.

The sent mail list moves only in the next-page direction. If there is a next page, Data.Meta.Page.HasNext is true, and you pass the NextCursor of the same response back to Cursor of the next request.

Response example

Unity

// success.Data is SentMailListResponseData
SentMailListResponseData data = success.Data;

foreach (SentMailListItem item in data.Items)
{
    // item.MailId         = "0196f7c3-8b2e-7f4d-a123-9c8d7e6f5a4b"
    // item.Title          = "출석 보상 우편"
    // item.MailStatus     = SentMailListItemMailStatus.Active
    // item.MailCategory   = "DEFAULT"
    // item.RecipientCount = 1
    Debug.Log($"{item.MailId} {item.Title} ({item.MailStatus})");
}

bool hasNext       = data.Meta?.Page?.HasNext ?? false;
string? nextCursor = data.Meta?.Page?.NextCursor;

Response status

The returned object MailboxGetSentMailsResult branches into one of the cases below. We recommend handling it with a switch statement.

Response case	Description	App client handling
Success	Sent mail list retrieval succeeded. Data contains the list and the pagination information.	Show the list, and retrieve the next page if needed
Failure	Common Failure. See Common error handling.	Handle according to the common error handling criteria
UnknownOutcome	A new result that this SDK version does not recognize.	Treat it as a failure and record the result code

Get details of a single mail item

GetMailAsync

Call GetMailAsync() to check the latest status, body, and attached item information of a specific sent mail item. Use it to check the status of a single mail item right away based on a MailId you already know. You can also use this method to check the status again right after sending or to check whether Revoked has been applied after a recall.

Call parameters

Field name	Type	Required	Description
request	GetMailRequest	Required	Request that specifies the sent mail to retrieve
context	ApiCallContext?	Optional	Per-call settings object. If omitted, the default values are used.

GetMailRequest

Field name	Type	Required	Description
MailId	string	Required	Identifier of the sent mail to retrieve

Call example

See the example below and the response status for the success result of MailboxGetMailResult and the domain-specific results (Outcome) of this method. For the result model and handling principles of common failures (Failure) returned when the request cannot be performed, see Common error handling.

Unity

using Hive.Axyl.Mailbox;
using Hive.Axyl.Core;

IMailboxService mailbox = HiveCore.Resolve<IMailboxService>();

var result = await mailbox.GetMailAsync(new GetMailRequest {
    MailId = storedMailId,
});

switch (result)
{
    case MailboxGetMailResult.Success success:
        Debug.Log($"{success.Data.Title}: {success.Data.MailStatus}");
        break;

    case MailboxGetMailResult.Failure failure:
        HiveError err = failure.Problem;
        Debug.LogError($"[{err.Code}] {err.Message} (trace: {err.TraceId})");
        break;

    default:
        Debug.LogWarning($"Unhandled result: {result.GetType().Name}");
        break;
}

Response data

On success, the result is contained in Data (MailResponseData) of MailboxGetMailResult.Success. Check the sent mail status, the expiration time, and whether there are attached items together to determine the operational status.

All fields except Data.MailCategory are declared with types that can hold null, so check whether a value is null before you show it on the screen or pass it to the next call.

Field name	Type	Required	Description
Data.MailId	string?	Optional	Sent mail identifier
Data.MailCategory	string	Required	Mailbox category. "DEFAULT" if no category was specified when the mail was sent
Data.MailContentType	MailMailContentType?	Optional	Mail content type
Data.SenderType	MailSenderType?	Optional	Sender type
Data.SenderId	string?	Optional	Sender identifier
Data.SenderDisplayName	string?	Optional	Sender name shown on the mail screen
Data.RecipientScope	MailRecipientScope?	Optional	Recipient scope. Broadcast or Direct
Data.Title	string?	Optional	Mail title
Data.Body	string?	Optional	Mail body
Data.Language	LanguageCode?	Optional	Mail language
Data.MailExtension	string?	Optional	Mail policy string defined by the app. Used to store app policy information such as mail display conditions or claim conditions. The server does not interpret this value and stores it as is
Data.ExpiresAt	DateTimeOffset?	Optional	Mail expiration time
Data.MailStatus	MailMailStatus?	Optional	Current sent mail status. Active, Revoked, Expired
Data.ClosedAt	DateTimeOffset?	Optional	Mail close time. The UTC time when the mail status changed to Expired or Revoked. null in the Active status
Data.CreatedAt	DateTimeOffset?	Optional	Mail creation time
Data.RecipientPlayerIds	IReadOnlyList<long>?	Optional	List of recipient Player IDs. null for mail sent to all users
Data.Attachments	IReadOnlyList<MailAttachment>?	Optional	List of attached items. null or empty for mail whose MailContentType is Text

MailAttachment

MailAttachment is each item of Data.Attachments. It corresponds to the AttachmentItem passed when sending, and the app reads these values to check which attached items were sent and how many.

Field name	Type	Required	Description
AttachmentType	string?	Optional	Attached item type defined by the app
ReferenceId	string?	Optional	Attached item reference ID
Quantity	int?	Optional	Quantity to grant
MailId	string?	Optional	Identifier of the sent mail that the attached item belongs to
CreatedAt	DateTimeOffset?	Optional	UTC time when the attached item was created

Response example

Unity

// success.Data is MailResponseData
MailResponseData data = success.Data;

// data.MailId          = "0196f7c3-8b2e-7f4d-a123-9c8d7e6f5a4b"
// data.Title           = "출석 보상 우편"
// data.Body            = "오늘도 접속해 주셔서 감사합니다."
// data.MailStatus      = MailMailStatus.Active
// data.MailContentType = MailMailContentType.Attachment
// data.SenderType      = MailSenderType.ProjectSystem
// data.SenderId        = "app-system"
// data.ExpiresAt       = 2026-06-17T00:00:00+00:00
Debug.Log($"{data.Title}: {data.MailStatus}");

Response status

The returned object MailboxGetMailResult branches into one of the cases below. We recommend handling it with a switch statement.

Response case	Description	App client handling
Success	Single mail detail retrieval succeeded. Data contains the mail details.	Apply the latest information, such as the mail status and expiration time
Failure	Common Failure. See Common error handling.	Handle according to the common error handling criteria
UnknownOutcome	A new result that this SDK version does not recognize.	Treat it as a failure and record the result code

To track the sent mail status, choose list retrieval or detail retrieval to suit the situation. Use list retrieval to check the overall status or the history of multiple mail items, and use detail retrieval to check MailStatus and ExpiresAt of a specific mail item right away.

Learn more

• Get received mail
• Mark mail as read
• Delete sent mail
• Recall mail