Skip to content

Get received mail

Use GetReceivedMailsAsync() and GetReceivedMailAsync() to retrieve the received mail list and details. To track the processing status of received mail, we recommend getting the overall status with list retrieval and checking MailRecipientId, TextReadAt, and AttachmentReadAt of a specific mail item with detail retrieval.

1. Prepare the retrieval conditions

Received mail retrieval is divided into list retrieval and single-item detail retrieval. For list retrieval, prepare the filter conditions; for single-item retrieval, prepare the MailRecipientId you found in the list response.

Organize the list retrieval conditions

Retrieve the list by combining language, category, content type, read status, and pagination conditions in GetReceivedMailsRequest. To check only mail that has not been read yet or mail whose attached items have not been claimed, we recommend explicitly setting TextRead and AttachmentRead to false.

  • Language: Language of the mail to retrieve
  • MailCategory: Mail category filter. If omitted, no category condition is applied
  • MailContentType: Content type filter. Text or Attachment. If omitted, no content type condition is applied
  • TextRead, AttachmentRead: Read status filters. If omitted, no read status condition is applied
  • Cursor, Direction, Size: Reference point for the next page, retrieval direction, and page size

MailCategory, MailContentType, TextRead, and AttachmentRead apply their conditions only when you specify a value. Therefore, to show all mail, as on the first mailbox screen, omit all four filters. If the app divides the mailbox into categories, specify the category that matches the screen in MailCategory when you retrieve the list.

MailRecipientId for single-item retrieval

For GetReceivedMailAsync(), use ReceivedMailListItem.MailRecipientId from the list response. However, you cannot retrieve the details of received mail that has been recalled, has expired, or has been deleted; in this case, the retrieval request returns a common failure (Failure).

2. Get the received mail list

Method

GetReceivedMailsAsync

Call GetReceivedMailsAsync() to retrieve the list of mail the user received and the pagination information. On the mailbox screen, load this list first, and check the body and attached item details with detail retrieval in the next step. Expired mail, recalled mail, and deleted mail do not appear in the received mail list results.

Call parameters

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

GetReceivedMailsRequest

Field name Type Required Description
Language LanguageCode? Optional Language of the mail to retrieve
MailCategory string? Optional Mail category filter. If omitted, no category condition is applied and all categories are retrieved
MailContentType ReceivedMailSearchRequestMailContentType? Optional Content type filter. Text, Attachment. If omitted, no content type condition is applied and all types are retrieved
TextRead bool? Optional Body read status filter. true retrieves only mail whose body has been read, and false retrieves only mail whose body has not been read. If omitted, no body read status condition is applied and all mail is retrieved regardless of whether it has been read
AttachmentRead bool? Optional Attached item claim status filter. true retrieves only mail whose attached items have been claimed, and false retrieves only mail whose attached items have not been claimed. If omitted, no attached item claim status condition is applied and all mail is retrieved regardless of whether the items have been claimed
Cursor string? Optional Cursor for page retrieval. NextCursor or PreviousCursor of the previous response
Direction ReceivedMailSearchRequestDirection? Optional Retrieval direction. Previous or Next. If omitted, Next is applied
Size int Optional Number of mail items to retrieve at a time. Minimum 1, maximum 50, default 10

Call example

See the example below and the response status for the success result of MailboxGetReceivedMailsResult 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.

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

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

var result = await mailbox.GetReceivedMailsAsync(new GetReceivedMailsRequest {
    Language = LanguageCode.Ko,
    Size     = 20,
});

switch (result)
{
    case MailboxGetReceivedMailsResult.Success success:
        foreach (ReceivedMailListItem item in success.Data.Items)
            Debug.Log($"{item.MailRecipientId} {item.Title}");
        break;

    case MailboxGetReceivedMailsResult.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;
}

A list item (ReceivedMailListItem) contains only summary information such as the title, received time, and read time. Check the body and attached items with detail retrieval in the next step.

Response data

On success, the result is contained in Data (ReceivedMailListResponseData) of MailboxGetReceivedMailsResult.Success. Items contains the summary list of received mail, and Meta contains the pagination information.

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

ReceivedMailListItem

ReceivedMailListItem 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
MailRecipientId string? Optional Received mail identifier. Used for detail retrieval and marking mail as read
MailId string? Optional Original sent mail identifier
Title string? Optional Mail title
SenderId string? Optional Sender identifier
SenderDisplayName string? Optional Sender name shown on the mail screen
SenderType ReceivedMailListItemSenderType? Optional Sender type. Admin, HiveSystem, ProjectSystem, User
MailCategory string? Optional Mail category
MailContentType ReceivedMailListItemMailContentType? Optional Mail content type. Text, Attachment
DeliveredAt DateTimeOffset? Optional Mail delivery time
TextReadAt DateTimeOffset? Optional Time the body was marked as read. null before it is marked as read
AttachmentReadAt DateTimeOffset? Optional Time the attached items were marked as claimed. null before they are marked as claimed
ExpiresAt DateTimeOffset? Optional Mail expiration time
RecipientPlayerId long? Optional Recipient Player ID

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.HasPrevious bool? Optional Whether a previous page exists
Page.PreviousCursor string? Optional Cursor value used to retrieve the previous page

The received mail list supports page navigation in both directions, forward and backward. To move to the next page, keep Direction as Next and pass the response's NextCursor to Cursor of the next request; to go back to the previous page, set Direction to Previous and pass the response's PreviousCursor to Cursor. Use HasNext and HasPrevious to determine whether there is a page to move to.

Response example

// success.Data.Items[0]
// MailRecipientId  = "0196f7c4-1d5a-7b3e-9f20-4c6b8a2e1d07"
// MailId           = "0196f7c3-8b2e-7f4d-a123-9c8d7e6f5a4b"
// Title            = "출석 보상 안내"
// SenderId         = "system"
// SenderType       = ReceivedMailListItemSenderType.ProjectSystem
// MailContentType  = ReceivedMailListItemMailContentType.Attachment
// TextReadAt       = null   // Body not read
// AttachmentReadAt = null   // Attached items not claimed
//
// success.Data.Meta.Page.HasNext    = true
// success.Data.Meta.Page.NextCursor = "eyJvZmZzZXQiOjIwfQ=="

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

Response status

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

Response case Description App client handling
Success Received mail list retrieval succeeded. Data.Items contains the summary list. Show the list on the mailbox screen
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

3. Get received mail details

Method

GetReceivedMailAsync

Call GetReceivedMailAsync() to check the body, status, and attached item information of a single received mail item. To show a specific mail item on the details screen, we recommend retrieving Mail.Title, Mail.Body, Mail.MailStatus, TextReadAt, and AttachmentReadAt together with this method. You cannot retrieve expired, recalled, or deleted mail with this method. Therefore, when detail retrieval succeeds, Mail.MailStatus contains Active.

Call parameters

Field name Type Required Description
request GetReceivedMailRequest Required Identifier and language of the received mail whose details to retrieve
context ApiCallContext? Optional Per-call settings object. If omitted, the default values are used.

GetReceivedMailRequest

Field name Type Required Description
MailRecipientId string Required Identifier of the received mail whose details to retrieve. Use the MailRecipientId of the list item
Language LanguageCode Required Language of the mail body to retrieve. There is no default value, so you must specify it

If there is no translation for the requested language, the server returns the title and body written in the mail's default language.

Call example

See the example below and the response status for the success result of MailboxGetReceivedMailResult 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.

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

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

// item is the ReceivedMailListItem from the list retrieval result.
if (item.MailRecipientId == null)
    return;

var result = await mailbox.GetReceivedMailAsync(new GetReceivedMailRequest {
    MailRecipientId = item.MailRecipientId,
    Language        = LanguageCode.Ko,
});

switch (result)
{
    case MailboxGetReceivedMailResult.Success success:
        Mail? mail = success.Data.Mail;
        bool bodyRead = success.Data.TextReadAt.HasValue;
        if (mail != null)
            Debug.Log($"{mail.Title}: {mail.Body} ({mail.MailStatus}) / bodyRead={bodyRead}");
        break;

    case MailboxGetReceivedMailResult.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 (MailRecipientResponseData) of MailboxGetReceivedMailResult.Success. Check the body and status in Mail, and the received time and read times at the top level of the response.

All fields except Mail.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.MailRecipientId string? Optional Received mail identifier
Data.Mail Mail? Optional Mail body, status, and attached item information
Data.RecipientPlayerId long? Optional Recipient Player ID
Data.DeliveredAt DateTimeOffset? Optional Mail delivery time
Data.TextReadAt DateTimeOffset? Optional Time the body was marked as read. null before it is marked as read
Data.AttachmentReadAt DateTimeOffset? Optional Time the attached items were marked as claimed. null before they are marked as claimed
Data.ExpiresAt DateTimeOffset? Optional Mail expiration time

Mail

Data.Mail is an object that contains the content and status of the original mail. Use it to show the title, body, and attached items on the details screen.

Field name Type Required Description
MailId string? Optional Original sent mail identifier
MailCategory string Required Mailbox category. "DEFAULT" if no category was specified when the mail was sent
MailContentType MailMailContentType? Optional Mail content type. Text, Attachment
SenderType MailSenderType? Optional Sender type. Admin, HiveSystem, ProjectSystem, User
SenderId string? Optional Sender identifier
SenderDisplayName string? Optional Sender name shown on the mail screen
RecipientScope MailRecipientScope? Optional Recipient scope. Broadcast, Direct
RecipientPlayerIds IReadOnlyList<long>? Optional List of recipient PlayerId values. null for mail sent to all users
Title string? Optional Mail title
Body string? Optional Mail body
Language LanguageCode? Optional Default language of the mail
MailExtension string? Optional Policy string defined by the app. The server does not interpret this value and stores the string as is
ExpiresAt DateTimeOffset? Optional Mail expiration time
MailStatus MailMailStatus? Optional Status of the original mail. Active, Revoked, Expired
ClosedAt DateTimeOffset? Optional Mail close time. The UTC time when the status changed to Expired or Revoked. null if Active
CreatedAt DateTimeOffset? Optional Mail creation time
Attachments IReadOnlyList<MailAttachment>? Optional List of attached items. null or empty for mail whose MailContentType is Text

MailAttachment

MailAttachment is each item of Mail.Attachments. The app reads these values to determine which attached items to grant and how many. It corresponds to the AttachmentItem passed when sending.

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 original sent mail that the attached item belongs to
CreatedAt DateTimeOffset? Optional UTC time when the attached item was created

Response example

// success.Data
// MailRecipientId   = "0196f7c4-1d5a-7b3e-9f20-4c6b8a2e1d07"
// Mail.Title        = "출석 보상 안내"
// Mail.Body         = "출석 보상을 확인하세요."
// Mail.MailStatus   = MailMailStatus.Active
// RecipientPlayerId = 1024
// DeliveredAt       = 2026-06-10T09:00:00+00:00
// TextReadAt        = null   // Body not read
// AttachmentReadAt  = null   // Attached items not claimed
// ExpiresAt         = 2026-06-24T09:00:00+00:00

Response status

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

Response case Description App client handling
Success Mail detail retrieval succeeded. Data.Mail contains the body, status, and attached items. Show the details screen, and then decide whether to mark the mail as read
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

Next steps

If the user has read the received mail body or the app has determined that the attached items were checked or downloaded, we recommend updating the mail status in Mark mail as read. To clean up mail in the mailbox, see Delete received mail.

To track the processing status of received mail, we recommend combining list retrieval, which shows the overall status, with single-item detail retrieval, which verifies TextReadAt and AttachmentReadAt of a specific mail item again.

Learn more