Mark mail as read

Call MarkMailAsReadAsync() to update the body read status and the attached item claim status of received mail.

1. Get received mail

Retrieve the received mail list and details in Get received mail, and then check the response results.

2. Determine the mail status

To know the exact status of received mail, you must look at whether the body has been read, whether the attached items have been claimed, whether the mail has been recalled, and whether it has expired, all together.

Values for determining the status

Mail status	Meaning	How to check
Read	The user has checked the mail body	`TextReadAt` is filled with the read time
Attached item claim status reflected	The app has determined that the attached items were checked and has reflected the status	`AttachmentReadAt` is filled with the claim time
Recalled	The sent mail has been recalled and removed from the inbox	It disappears from the list results, and detail retrieval with the same `MailRecipientId` fails
Expired	The expiration deadline has passed	The current time is past the `ExpiresAt` value received in advance. It also disappears from the list results

Value to check	Type	Meaning
`TextReadAt`	`DateTimeOffset?`	Time the mail body was marked as read. `null` before it is marked as read
`AttachmentReadAt`	`DateTimeOffset?`	Time the attached items were marked as claimed. `null` before they are marked as claimed
`ExpiresAt`	`DateTimeOffset?`	Mail expiration time
`Mail.MailStatus`	`MailMailStatus?`	Status of the original mail. One of `Active`, `Revoked`, or `Expired`. Mail whose detail retrieval succeeded contains `Active`

Distinguish the read status from the claim status

TextReadAt and AttachmentReadAt are null when they have not been processed yet. Therefore, determine whether they are unprocessed with TextReadAt.HasValue and AttachmentReadAt.HasValue.

The attached item feature that the Hive Axyl SDK provides is limited to marking the attached item claim status. The app must implement all actual saving, storing, claiming, and downloading of attached items, as well as their recall.

Warning

AttachmentReadAt is not a value that the Hive Axyl SDK fills automatically by detecting that the user actually checked or downloaded the attached items. It is filled only after the app client determines that the attached items were checked or downloaded, or receives the determination result from the app server, and then calls MarkMailAsReadAsync() with Attachment or All.

Therefore, for mail with attached items, handle checking the body and reflecting the attached item claim status separately. For example, for mail without attached items, you only need TextReadAt to determine whether the body has been read. However, for mail with attached items, opening the details does not automatically reflect the claim status, so handle it as follows.

The app client or app server determines that the attached items were checked or downloaded, and then the app processes the actual attached items.
The app client calls MarkMailAsReadAsync() to update the attached item claim status.
Determine whether the status was reflected with AttachmentReadAt in the response data. If you also need to check the latest status updated on another device, retrieve it again with GetReceivedMailAsync().
Update the app's mailbox UI according to the result.

3. Mark mail as read

When the user has checked the mail content, set Target to one of Text, Attachment, or All, and call the mark-as-read method. What the Hive Axyl SDK provides is not a feature that determines the attached item status by itself, but a method that updates the status based on a result the app has already determined.

Text: Marks only the mail body as read
Attachment: Updates only the status of the attached items that the app has determined were checked or downloaded
All: Updates both the body and the status of the attached items that the app has checked

MarkMailAsReadAsync

When you call MarkMailAsReadAsync(), it updates the read time according to the specified Target. The app client or the app server determines whether the attached items were checked or downloaded, and once that is determined, the app client sets Target to Attachment or All and makes the call. If the app server made the determination, the app client makes the call after it receives the result. After the call, check TextReadAt and AttachmentReadAt in the response to update the UI state.

You can call the mark-as-read method multiple times for the same mail, and even in this case, the first read time is kept as is.

Call parameters

Field name	Type	Required	Description
`request`	`MarkMailAsReadRequest`	Required	Identifier of the received mail to mark as read and the processing target
`context`	`ApiCallContext?`	Optional	Per-call settings object. If omitted, the default values are used.

MarkMailAsReadRequest

Field name	Type	Required	Description
`MailRecipientId`	`string`	Required	Identifier of the received mail to mark as read
`Target`	`MarkMailRequestTarget`	Required	Target to mark as read. `Text`, `Attachment`, `All`. There is no default value, so you must specify it. Update the attached item status with `Attachment` or `All` after the app determines that the attached items were checked or downloaded.

Call example

See the example below and the response status for the success result of MailboxMarkMailAsReadResult 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>();

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

var result = await mailbox.MarkMailAsReadAsync(new MarkMailAsReadRequest {
    MailRecipientId = item.MailRecipientId,
    Target          = MarkMailRequestTarget.All,
});

switch (result)
{
    case MailboxMarkMailAsReadResult.Success success:
        bool attachmentReceived = success.Data.AttachmentReadAt.HasValue;
        Debug.Log($"attachmentReceived={attachmentReceived}");
        break;

    case MailboxMarkMailAsReadResult.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 updated read times are contained in Data (MarkMailResponseData) of MailboxMarkMailAsReadResult.Success.

Field name	Type	Required	Description
`Data.MailRecipientId`	`string?`	Optional	Identifier of the received mail marked as read
`Data.TextReadAt`	`DateTimeOffset?`	Optional	Updated body read time. `null` if the body has not been processed yet
`Data.AttachmentReadAt`	`DateTimeOffset?`	Optional	Updated attached item claim time. `null` if the attached items have not been processed yet

Response example