수신 우편 정보 조회

GetReceivedMailsAsync()와 GetReceivedMailAsync()를 사용해 수신 우편 목록과 상세 정보를 조회합니다. 수신 우편 처리 상태를 추적할 때는 목록 조회로 전체 현황을 파악하고, 상세 조회로 특정 우편의 MailRecipientId, TextReadAt, AttachmentReadAt을 확인하는 것을 권장합니다.

1. 조회 조건 준비

수신 우편 조회는 목록 조회와 단일 상세 조회로 나뉩니다. 목록 조회에는 필터 조건을 준비하고, 단일 조회에는 목록 응답에서 확인한 MailRecipientId를 준비합니다.

목록 조회 조건 정리

GetReceivedMailsRequest로 언어, 카테고리, 본문 유형, 읽음 상태, 페이지네이션 조건을 조합해 목록을 조회합니다. 아직 읽지 않은 우편이나 첨부 아이템을 수령하지 않은 우편만 확인할 때는 TextRead와 AttachmentRead에 false를 명시하는 것을 권장합니다.

Language: 조회할 우편 언어
MailCategory: 우편 카테고리 필터. 생략하면 카테고리 조건을 적용하지 않음
MailContentType: 본문 유형 필터. Text 또는 Attachment. 생략하면 본문 유형 조건을 적용하지 않음
TextRead, AttachmentRead: 읽음 상태 필터. 생략하면 읽음 상태 조건을 적용하지 않음
Cursor, Direction, Size: 다음 페이지 기준점, 조회 방향, 페이지 크기

MailCategory, MailContentType, TextRead, AttachmentRead는 값을 지정했을 때만 해당 조건을 적용합니다. 따라서 우편함 첫 화면처럼 전체 우편을 보여 줄 때는 네 필터를 모두 생략합니다. 앱이 우편함 카테고리를 나눠 쓴다면 화면에 맞는 카테고리를 MailCategory에 지정해 조회하세요.

단일 조회에 사용할 MailRecipientId

GetReceivedMailAsync()에는 목록 응답의 ReceivedMailListItem.MailRecipientId를 사용합니다. 단, 회수되거나 만료되거나 삭제된 수신 우편은 상세 조회할 수 없으며, 이 경우 조회 요청은 공통 실패(Failure)를 반환합니다.

2. 수신 우편 목록 조회

GetReceivedMailsAsync

GetReceivedMailsAsync()를 호출해 사용자가 수신한 우편 목록과 페이지네이션 정보를 조회합니다. 우편함 화면에서는 이 목록을 먼저 불러오고, 본문과 첨부 아이템 상세는 다음 단계의 상세 조회에서 확인합니다. 만료된 우편, 회수된 우편, 삭제된 우편은 수신 우편 목록 조회 결과에 나타나지 않습니다.

호출 파라미터

필드명	타입	필수 여부	설명
`request`	`GetReceivedMailsRequest`	Required	수신 우편 목록 조회 조건
`context`	`ApiCallContext?`	Optional	호출 단위 설정 객체입니다. 생략하면 기본값이 사용됩니다.

GetReceivedMailsRequest

필드명	타입	필수 여부	설명
`Language`	`LanguageCode?`	Optional	조회할 우편 언어
`MailCategory`	`string?`	Optional	우편 카테고리 필터. 생략하면 카테고리 조건을 적용하지 않고 모든 카테고리를 조회
`MailContentType`	`ReceivedMailSearchRequestMailContentType?`	Optional	본문 유형 필터. `Text`, `Attachment`. 생략하면 본문 유형 조건을 적용하지 않고 모든 유형을 조회
`TextRead`	`bool?`	Optional	본문 읽음 상태 필터. `true`이면 본문을 읽은 우편만, `false`이면 본문을 읽지 않은 우편만 조회. 생략하면 본문 읽음 상태 조건을 적용하지 않고 읽음 여부와 관계없이 모두 조회
`AttachmentRead`	`bool?`	Optional	첨부 아이템 수령 상태 필터. `true`이면 첨부 아이템을 수령한 우편만, `false`이면 수령하지 않은 우편만 조회. 생략하면 첨부 아이템 수령 상태 조건을 적용하지 않고 수령 여부와 관계없이 모두 조회
`Cursor`	`string?`	Optional	페이지 조회용 커서. 이전 응답의 `NextCursor` 또는 `PreviousCursor`
`Direction`	`ReceivedMailSearchRequestDirection?`	Optional	조회 방향. `Previous` 또는 `Next`. 생략하면 `Next`가 적용
`Size`	`int`	Optional	한 번에 조회할 우편 수. 최소 `1`, 최대 `50`, 기본값 `10`

호출 예시

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

Unity

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($"처리되지 않은 결과: {result.GetType().Name}");
        break;
}

목록 항목(ReceivedMailListItem)에는 제목, 수신 시각, 읽음 시각 같은 요약 정보만 담깁니다. 본문과 첨부 아이템은 다음 단계의 상세 조회에서 확인합니다.

응답 데이터

성공 시 MailboxGetReceivedMailsResult.Success의 Data(ReceivedMailListResponseData)에 결과가 담깁니다. Items에 수신 우편 요약 목록이, Meta에 페이지네이션 정보가 들어 있습니다.

필드명	타입	필수 여부	설명
`Data.Items`	`IReadOnlyList<ReceivedMailListItem>`	Required	조회된 수신 우편 요약 목록. 조건에 맞는 우편이 없으면 빈 목록
`Data.Meta`	`MetaPage?`	Optional	페이지네이션 정보

ReceivedMailListItem

ReceivedMailListItem은 Data.Items의 각 항목입니다. 모든 필드가 null을 담을 수 있는 형식으로 선언되어 있으므로, 값을 화면에 표시하거나 다음 호출에 넘기기 전에 null인지 먼저 확인하세요.

필드명	타입	필수 여부	설명
`MailRecipientId`	`string?`	Optional	수신 우편 식별자. 상세 조회와 읽음 처리에 사용
`MailId`	`string?`	Optional	원본 발신 우편 식별자
`Title`	`string?`	Optional	우편 제목
`SenderId`	`string?`	Optional	발신자 식별자
`SenderDisplayName`	`string?`	Optional	우편 화면에 표시하는 발신자 이름
`SenderType`	`ReceivedMailListItemSenderType?`	Optional	발신자 유형. `Admin`, `HiveSystem`, `ProjectSystem`, `User`
`MailCategory`	`string?`	Optional	우편 카테고리
`MailContentType`	`ReceivedMailListItemMailContentType?`	Optional	우편 내용 유형. `Text`, `Attachment`
`DeliveredAt`	`DateTimeOffset?`	Optional	우편 전달 시각
`TextReadAt`	`DateTimeOffset?`	Optional	본문 읽음 처리 시각. 읽음 처리 전에는 `null`
`AttachmentReadAt`	`DateTimeOffset?`	Optional	첨부 아이템 수령 처리 시각. 수령 처리 전에는 `null`
`ExpiresAt`	`DateTimeOffset?`	Optional	우편 만료 시각
`RecipientPlayerId`	`long?`	Optional	수신자 Player ID

MetaPage

Data.Meta는 페이지 이동에 사용하는 커서 정보를 담습니다.

필드명	타입	필수 여부	설명
`Page`	`AxylCursorPagination?`	Optional	커서 페이지 정보
`Page.HasNext`	`bool?`	Optional	다음 페이지 존재 여부
`Page.NextCursor`	`string?`	Optional	다음 페이지를 조회할 때 사용하는 커서 값
`Page.HasPrevious`	`bool?`	Optional	이전 페이지 존재 여부
`Page.PreviousCursor`	`string?`	Optional	이전 페이지를 조회할 때 사용하는 커서 값

수신 우편 목록은 앞뒤 양방향으로 페이지를 이동합니다. 다음 페이지로 이동할 때는 Direction을 Next로 두고 응답의 NextCursor를 다음 요청의 Cursor에 전달하고, 이전 페이지로 돌아갈 때는 Direction을 Previous로 지정하고 응답의 PreviousCursor를 Cursor에 전달합니다. 이동할 페이지가 있는지는 HasNext와 HasPrevious로 판단합니다.

응답 예시

Unity

// 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   // 본문 미읽음
// AttachmentReadAt = null   // 첨부 아이템 미수령
//
// 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;

응답 상태

반환 객체 MailboxGetReceivedMailsResult는 아래 케이스 중 하나로 분기됩니다. switch 구문으로 처리를 권장합니다.

응답 케이스	설명	앱 클라이언트 대응
`Success`	수신 우편 목록 조회 성공. `Data.Items`에 요약 목록이 담깁니다.	우편함 화면에 목록 표시
`Failure`	공통 Failure입니다. 공통 오류 처리를 참조하세요.	공통 오류 처리 기준에 따라 처리
`UnknownOutcome`	이 SDK 버전이 알지 못하는 신규 결과입니다.	실패로 처리하고 결과 코드를 기록

3. 수신 우편 상세 정보 조회

GetReceivedMailAsync

GetReceivedMailAsync()를 호출해 단일 수신 우편의 본문, 상태, 첨부 아이템 정보를 확인합니다. 특정 우편을 상세 화면에 표시할 때는 이 메서드로 Mail.Title, Mail.Body, Mail.MailStatus, TextReadAt, AttachmentReadAt을 함께 조회하는 것을 권장합니다. 만료되거나 회수되거나 삭제된 우편은 이 메서드로 조회할 수 없습니다. 따라서 상세 조회에 성공하면 Mail.MailStatus에는 Active가 담깁니다.

호출 파라미터

필드명	타입	필수 여부	설명
`request`	`GetReceivedMailRequest`	Required	상세를 조회할 수신 우편 식별자와 언어
`context`	`ApiCallContext?`	Optional	호출 단위 설정 객체입니다. 생략하면 기본값이 사용됩니다.

GetReceivedMailRequest

필드명	타입	필수 여부	설명
`MailRecipientId`	`string`	Required	상세를 조회할 수신 우편 식별자. 목록 항목의 `MailRecipientId`를 사용
`Language`	`LanguageCode`	Required	조회할 우편 본문의 언어. 기본값이 없으므로 반드시 지정

요청한 언어의 번역이 없으면 서버는 우편의 기본 언어로 작성한 제목과 본문을 반환합니다.

호출 예시

MailboxGetReceivedMailResult의 성공 결과와 이 메서드의 도메인별 결과(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.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($"처리되지 않은 결과: {result.GetType().Name}");
        break;
}

응답 데이터

성공 시 MailboxGetReceivedMailResult.Success의 Data(MailRecipientResponseData)에 결과가 담깁니다. Mail에서 본문과 상태를, 응답 최상위에서 수신 시각과 읽음 시각을 확인합니다.

Mail.MailCategory를 제외한 모든 필드가 null을 담을 수 있는 형식으로 선언되어 있으므로, 값을 화면에 표시하거나 다음 호출에 넘기기 전에 null인지 먼저 확인하세요.

필드명	타입	필수 여부	설명
`Data.MailRecipientId`	`string?`	Optional	수신 우편 식별자
`Data.Mail`	`Mail?`	Optional	우편 본문, 상태, 첨부 아이템 정보
`Data.RecipientPlayerId`	`long?`	Optional	수신자 Player ID
`Data.DeliveredAt`	`DateTimeOffset?`	Optional	우편 전달 시각
`Data.TextReadAt`	`DateTimeOffset?`	Optional	본문 읽음 처리 시각. 읽음 처리 전에는 `null`
`Data.AttachmentReadAt`	`DateTimeOffset?`	Optional	첨부 아이템 수령 처리 시각. 수령 처리 전에는 `null`
`Data.ExpiresAt`	`DateTimeOffset?`	Optional	우편 만료 시각

Mail

Data.Mail은 우편 원본의 내용과 상태를 담는 객체입니다. 상세 화면의 제목, 본문, 첨부 아이템 표시에 사용합니다.

필드명	타입	필수 여부	설명
`MailId`	`string?`	Optional	원본 발신 우편 식별자
`MailCategory`	`string`	Required	우편함 카테고리. 발송할 때 카테고리를 지정하지 않았으면 `"DEFAULT"`
`MailContentType`	`MailMailContentType?`	Optional	우편 본문 유형. `Text`, `Attachment`
`SenderType`	`MailSenderType?`	Optional	발신자 유형. `Admin`, `HiveSystem`, `ProjectSystem`, `User`
`SenderId`	`string?`	Optional	발신자 식별자
`SenderDisplayName`	`string?`	Optional	우편 화면에 표시하는 발신자 이름
`RecipientScope`	`MailRecipientScope?`	Optional	수신 대상 범위. `Broadcast`, `Direct`
`RecipientPlayerIds`	`IReadOnlyList<long>?`	Optional	수신자 `PlayerId` 목록. 모든 사용자에게 보낸 우편이면 `null`
`Title`	`string?`	Optional	우편 제목
`Body`	`string?`	Optional	우편 본문
`Language`	`LanguageCode?`	Optional	우편 기본 언어
`MailExtension`	`string?`	Optional	앱에서 정의한 정책 문자열. 서버는 이 값을 해석하지 않고 문자열 그대로 저장
`ExpiresAt`	`DateTimeOffset?`	Optional	우편 만료 시각
`MailStatus`	`MailMailStatus?`	Optional	원본 우편 상태. `Active`, `Revoked`, `Expired`
`ClosedAt`	`DateTimeOffset?`	Optional	우편 종료 시각. 상태가 `Expired` 또는 `Revoked`로 바뀐 UTC 시각. `Active`이면 `null`
`CreatedAt`	`DateTimeOffset?`	Optional	우편 생성 시각
`Attachments`	`IReadOnlyList<MailAttachment>?`	Optional	첨부 아이템 목록. `MailContentType`이 `Text`인 우편은 `null`이거나 비어 있음

MailAttachment

MailAttachment는 Mail.Attachments의 각 항목입니다. 앱은 이 값을 읽어 어떤 첨부 아이템을 몇 개 지급할지 판단합니다. 발송 시 전달한 AttachmentItem에 대응합니다.

필드명	타입	필수 여부	설명
`AttachmentType`	`string?`	Optional	앱에서 정의한 첨부 아이템 타입
`ReferenceId`	`string?`	Optional	첨부 아이템 참조 ID
`Quantity`	`int?`	Optional	지급 수량
`MailId`	`string?`	Optional	첨부 아이템이 속한 원본 발신 우편 식별자
`CreatedAt`	`DateTimeOffset?`	Optional	첨부 아이템이 생성된 UTC 시각

응답 예시

Unity

// 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   // 본문 미읽음
// AttachmentReadAt  = null   // 첨부 아이템 미수령
// ExpiresAt         = 2026-06-24T09:00:00+00:00

응답 상태

반환 객체 MailboxGetReceivedMailResult는 아래 케이스 중 하나로 분기됩니다. switch 구문으로 처리를 권장합니다.

응답 케이스	설명	앱 클라이언트 대응
`Success`	우편 상세 조회 성공. `Data.Mail`에 본문, 상태, 첨부 아이템이 담깁니다.	상세 화면 표시 후 읽음 처리 여부 결정
`Failure`	공통 Failure입니다. 공통 오류 처리를 참조하세요.	공통 오류 처리 기준에 따라 처리
`UnknownOutcome`	이 SDK 버전이 알지 못하는 신규 결과입니다.	실패로 처리하고 결과 코드를 기록

다음 단계

수신 우편 본문을 읽었거나 앱에서 첨부 아이템 확인 또는 다운로드 완료를 판단했다면 우편 읽음 처리에서 우편 상태를 갱신하는 것을 권장합니다. 우편함에서 우편을 정리하려면 수신 우편 삭제를 참조하세요.

수신 우편 처리 상태를 추적할 때는 목록 조회로 전체 현황을 파악하고, 단일 상세 조회로 특정 우편의 TextReadAt과 AttachmentReadAt을 다시 검증하는 조합을 권장합니다.

수신 우편 정보 조회

1. 조회 조건 준비

목록 조회 조건 정리

단일 조회에 사용할 MailRecipientId

2. 수신 우편 목록 조회

호출 파라미터

GetReceivedMailsRequest

호출 예시

응답 데이터

ReceivedMailListItem

MetaPage

응답 예시

응답 상태

3. 수신 우편 상세 정보 조회

호출 파라미터

GetReceivedMailRequest

호출 예시

응답 데이터

Mail

MailAttachment

응답 예시

응답 상태

다음 단계

더 알아보기