우편 읽음 처리

MarkMailAsReadAsync()를 호출해 수신 우편의 본문 읽음 상태와 첨부 아이템 수령 상태를 갱신합니다.

1. 수신 우편 정보 조회

수신 우편 정보 조회에서 수신 우편 목록과 상세 정보를 조회한 뒤 응답 결과를 확인합니다.

2. 우편 상태 판단

수신 우편은 본문 읽음 여부, 첨부 아이템 수령 여부, 회수 여부, 만료 여부를 함께 봐야 정확한 상태를 알 수 있습니다.

상태 판단 값

우편 상태 구분	의미	확인 기준
읽음	사용자가 우편 본문을 확인한 상태	`TextReadAt`에 읽음 시각이 채워짐
첨부 아이템 수령 상태 반영	앱이 첨부 아이템 확인 완료를 판단해 상태를 반영한 상태	`AttachmentReadAt`에 수령 시각이 채워짐
회수	발신 우편이 회수되어 수신함에서 제거된 상태	목록 조회 결과에서 사라지고, 같은 `MailRecipientId`로 상세 조회하면 조회에 실패
만료	만료 기한이 지난 상태	미리 받아 둔 `ExpiresAt`이 현재 시각을 지남. 목록 조회 결과에서도 사라짐

확인 값	타입	의미
`TextReadAt`	`DateTimeOffset?`	우편 본문 읽음 처리 시각. 읽음 처리 전에는 `null`
`AttachmentReadAt`	`DateTimeOffset?`	첨부 아이템 수령 처리 시각. 수령 처리 전에는 `null`
`ExpiresAt`	`DateTimeOffset?`	우편 만료 시각
`Mail.MailStatus`	`MailMailStatus?`	원본 우편 상태. `Active`, `Revoked`, `Expired` 중 하나. 상세 조회에 성공한 우편에는 `Active`가 담김

읽음과 수령 상태 구분

TextReadAt과 AttachmentReadAt은 아직 처리되지 않았을 때 null입니다. 따라서 미처리 여부는 TextReadAt.HasValue와 AttachmentReadAt.HasValue로 판단합니다.

Hive Axyl SDK가 제공하는 첨부 아이템 기능은 첨부 아이템 수령 상태를 표시하는 기능에 한정됩니다. 실제 첨부 아이템의 저장, 보관, 수령, 다운로드 처리와 회수는 모두 앱에서 직접 구현해야 합니다.

Warning

AttachmentReadAt은 Hive Axyl SDK가 사용자의 실제 첨부 아이템 확인 또는 다운로드를 감지해 자동으로 채우는 값이 아닙니다. 앱 클라이언트가 첨부 아이템 확인이나 다운로드 완료를 직접 판단하거나 앱 서버에서 판단 결과를 받은 뒤, MarkMailAsReadAsync()를 Attachment 또는 All로 호출해야 채워집니다.

따라서 첨부 아이템이 있는 우편은 본문 확인과 첨부 아이템 수령 상태 반영을 분리해 처리해야 합니다. 예를 들어, 첨부 아이템이 없는 우편은 TextReadAt만으로 본문 읽음 여부를 판단하면 됩니다. 하지만 첨부 아이템이 있는 우편은 상세 내용을 열어도 수령 상태가 자동으로 반영되지 않으므로, 아래와 같이 처리해야 합니다.

앱 클라이언트 또는 앱 서버가 첨부 아이템 확인이나 다운로드 완료를 판단한 뒤 앱에서 실제 첨부 아이템을 처리합니다.
앱 클라이언트가 MarkMailAsReadAsync()를 호출해 첨부 아이템 수령 상태를 갱신합니다.
응답 데이터의 AttachmentReadAt으로 상태 반영 여부를 판단합니다. 다른 기기에서 갱신된 최신 상태까지 확인해야 하면 GetReceivedMailAsync()로 다시 조회합니다.
그 결과에 맞춰 앱 우편함 UI를 갱신합니다.

3. 우편 읽음 처리

사용자가 우편 내용을 확인했다면 Target을 Text, Attachment, All 중 하나로 정해 읽음 처리 메서드를 호출합니다. Hive Axyl SDK가 제공하는 것은 첨부 아이템 상태를 직접 판정하는 기능이 아니라, 앱이 이미 판단한 결과를 기준으로 상태를 갱신하는 메서드입니다.

Text: 우편 본문만 읽음 처리
Attachment: 앱에서 첨부 아이템 확인 또는 다운로드 완료로 판단한 첨부 아이템 상태만 갱신
All: 본문과 앱이 확인한 첨부 아이템 상태를 함께 갱신

MarkMailAsReadAsync

MarkMailAsReadAsync()를 호출하면 지정한 Target에 맞춰 읽음 시각을 갱신합니다. 첨부 아이템 확인이나 다운로드 완료는 앱 클라이언트나 앱 서버가 판단하며, 판단이 끝나면 앱 클라이언트가 Target을 Attachment 또는 All로 정해 호출합니다. 앱 서버가 판단했다면 앱 클라이언트가 그 결과를 받은 뒤 호출합니다. 호출한 뒤에는 응답의 TextReadAt과 AttachmentReadAt을 확인해 UI 상태를 갱신하세요.

읽음 처리 메서드는 같은 우편에 여러 번 호출할 수 있으며, 이 경우에도 최초 읽음 처리 시각을 그대로 유지합니다.

호출 파라미터

필드명	타입	필수 여부	설명
`request`	`MarkMailAsReadRequest`	Required	읽음 처리할 수신 우편 식별자와 처리 대상
`context`	`ApiCallContext?`	Optional	호출 단위 설정 객체입니다. 생략하면 기본값이 사용됩니다.

MarkMailAsReadRequest

필드명	타입	필수 여부	설명
`MailRecipientId`	`string`	Required	읽음 처리할 수신 우편 식별자
`Target`	`MarkMailRequestTarget`	Required	읽음 처리 대상. `Text`, `Attachment`, `All`. 기본값이 없으므로 반드시 지정합니다. 첨부 아이템 상태는 앱이 첨부 아이템 확인 또는 다운로드 완료를 판단한 뒤 `Attachment` 또는 `All`로 갱신합니다.

호출 예시

MailboxMarkMailAsReadResult의 성공 결과와 이 메서드의 도메인별 결과(Outcome)는 아래 예시와 응답 상태에서 확인합니다. 요청을 수행할 수 없을 때 반환하는 공통 실패(Failure)의 결과 모델과 처리 원칙은 공통 오류 처리를 참조하세요.

Unity

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

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

// item 은 수신 우편 목록 조회 결과의 ReceivedMailListItem 입니다.
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($"처리되지 않은 결과: {result.GetType().Name}");
        break;
}

응답 데이터

성공 시 MailboxMarkMailAsReadResult.Success의 Data(MarkMailResponseData)에 갱신된 읽음 시각이 담깁니다.

필드명	타입	필수 여부	설명
`Data.MailRecipientId`	`string?`	Optional	읽음 처리한 수신 우편 식별자
`Data.TextReadAt`	`DateTimeOffset?`	Optional	갱신된 본문 읽음 처리 시각. 아직 본문을 처리하지 않았으면 `null`
`Data.AttachmentReadAt`	`DateTimeOffset?`	Optional	갱신된 첨부 아이템 수령 처리 시각. 아직 첨부 아이템을 처리하지 않았으면 `null`

응답 예시