발신 우편 정보 조회
GetSentMailsAsync()와 GetMailAsync()를 사용해 발신 우편 목록과 단일 발신 우편 상세를 조회합니다. 발신 우편 전체 현황을 확인할 때는 목록 조회를, 특정 우편의 최신 상태를 확인할 때는 상세 조회를 사용합니다.
조회 준비
발신 우편 조회는 목록 조회와 단일 상세 조회로 나뉩니다. 목록 조회에는 필터 조건을 준비하고, 단일 상세 조회에는 발송 시 저장한 MailId를 준비합니다.
목록 조회 조건 준비
GetSentMailsRequest로 카테고리, 본문 유형, 상태, 페이지네이션 조건을 조합해 목록을 조회합니다. 운영 우편 이력을 주기적으로 확인할 때는 MailStatus와 MailContentType을 함께 사용해 필요한 우편만 조회하는 것을 권장합니다.
MailCategory: 조회할 우편함 카테고리. 생략하면 기본값인"DEFAULT"카테고리만 조회MailContentType: 본문 유형 필터.Text또는Attachment. 생략하면 본문 유형 조건을 적용하지 않음MailStatus: 상태 필터.Active,Revoked,Expired. 생략하면 상태 조건을 적용하지 않음Cursor,Size: 다음 페이지 기준점과 페이지 크기
단일 조회에 사용할 MailId
GetMailAsync()에는 발송 시 저장한 MailId를 사용합니다. 우편 회수나 만료 여부를 다시 확인할 때는 같은 MailId로 해당 우편 상세 정보를 다시 조회합니다.
발신 우편 상태 값
발신 우편 상태는 목록 응답의 SentMailListItem.MailStatus와 상세 응답의 MailResponseData.MailStatus로 확인합니다.
Active: 유효한 우편Revoked: 회수된 우편Expired: 만료된 우편
발신 우편 목록 조회에는 유효한(Active) 우편뿐 아니라 회수된(Revoked) 우편과 만료된(Expired) 우편도 발송 이력을 확인할 수 있도록 함께 포함됩니다. MailStatus를 지정하면 해당 상태의 우편만 조회하고, 생략하면 상태와 관계없이 모두 조회합니다. 삭제한 발신 우편만 발신 우편 목록 조회 결과에서 제외됩니다.
발신 우편 목록 조회
GetSentMailsAsync
GetSentMailsAsync()를 호출해 조회 조건에 맞는 발신 우편 목록과 페이지네이션 정보를 가져옵니다. 우편 전체 현황이나 발신 이력을 확인할 때 사용합니다. 운영 우편 목록을 계속 추적할 때는 응답의 Data.Meta.Page.HasNext와 NextCursor를 사용해 다음 페이지를 이어서 조회합니다.
호출 파라미터
| 필드명 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
request | GetSentMailsRequest | Required | 발신 우편 목록 조회 조건 |
context | ApiCallContext? | Optional | 호출 단위 설정 객체입니다. 생략하면 기본값이 사용됩니다. |
GetSentMailsRequest
| 필드명 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
MailCategory | string | Optional | 조회할 우편함 카테고리. 기본값 "DEFAULT", 최대 64자 |
MailContentType | SentMailSearchRequestMailContentType? | Optional | 본문 유형 필터. Text, Attachment |
MailStatus | SentMailSearchRequestMailStatus? | Optional | 상태 필터. Active, Revoked, Expired |
Cursor | string? | Optional | 다음 페이지 기준점. 이전 응답의 NextCursor |
Size | int | Optional | 한 번에 가져올 개수. 최소 1, 최대 50, 기본값 10 |
호출 예시
MailboxGetSentMailsResult의 성공 결과와 이 메서드의 도메인별 결과(Outcome)는 아래 예시와 응답 상태에서 확인합니다. 요청을 수행할 수 없을 때 반환하는 공통 실패(Failure)의 결과 모델과 처리 원칙은 공통 오류 처리를 참조하세요.
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($"처리되지 않은 결과: {result.GetType().Name}");
break;
}
응답 데이터
성공 시 MailboxGetSentMailsResult.Success의 Data(SentMailListResponseData)에 결과가 담깁니다. 목록은 Data.Items, 페이지네이션 정보는 Data.Meta에 들어 있습니다.
| 필드명 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
Data.Items | IReadOnlyList<SentMailListItem> | Required | 조회된 발신 우편 목록. 조건에 맞는 우편이 없으면 빈 목록 |
Data.Meta | MetaPage? | Optional | 페이지네이션 정보 |
SentMailListItem
SentMailListItem은 Data.Items의 각 항목입니다. 모든 필드가 null을 담을 수 있는 형식으로 선언되어 있으므로, 값을 화면에 표시하거나 다음 호출에 넘기기 전에 null인지 먼저 확인하세요.
| 필드명 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
MailId | string? | Optional | 발신 우편 식별자 |
Title | string? | Optional | 우편 제목 |
SenderDisplayName | string? | Optional | 우편 화면에 표시하는 발신자 이름 |
MailStatus | SentMailListItemMailStatus? | Optional | 발신 우편 상태. Active, Revoked, Expired |
MailCategory | string? | Optional | 우편함 카테고리 |
MailContentType | SentMailListItemMailContentType? | Optional | 우편 본문 유형. Text, Attachment |
ExpiresAt | DateTimeOffset? | Optional | 우편 만료 시각 |
CreatedAt | DateTimeOffset? | Optional | 우편 생성 시각 |
ClosedAt | DateTimeOffset? | Optional | 우편 종료 시각. 우편 상태가 Expired 또는 Revoked로 변경된 UTC 시각. Active 상태일 때는 null |
RecipientCount | long? | Optional | 수신 대상 수. 우편을 받은 전체 사용자 수 |
FirstRecipientPlayerId | long? | Optional | 수신자 목록 중 첫 번째 Player ID. 발신 우편 목록 표시용 요약 정보. 전체 수신자 목록은 단일 우편 상세 조회에서 확인. 모든 사용자에게 보낸 우편이면 null |
SenderId | string? | Optional | 발신자 식별자 |
MetaPage
Data.Meta는 페이지 이동에 사용하는 커서 정보를 담습니다.
| 필드명 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
Page | AxylCursorPagination? | Optional | 커서 페이지 정보 |
Page.HasNext | bool? | Optional | 다음 페이지 존재 여부 |
Page.NextCursor | string? | Optional | 다음 페이지를 조회할 때 사용하는 커서 값 |
Page에는 이전 페이지용 HasPrevious와 PreviousCursor도 있지만, 발신 우편 목록 조회는 이전 페이지 이동을 지원하지 않으므로 두 값은 항상 null입니다.
발신 우편 목록은 다음 페이지 방향으로만 이동합니다. 다음 페이지가 있으면 Data.Meta.Page.HasNext가 true이고, 같은 응답의 NextCursor를 다음 요청의 Cursor에 다시 전달합니다.
응답 예시
// success.Data 가 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;
응답 상태
반환 객체 MailboxGetSentMailsResult는 아래 케이스 중 하나로 분기됩니다. switch 구문으로 처리를 권장합니다.
| 응답 케이스 | 설명 | 앱 클라이언트 대응 |
|---|---|---|
Success | 발신 우편 목록 조회 성공. Data에 목록과 페이지네이션 정보가 담깁니다. | 목록 표시, 필요 시 다음 페이지 조회 |
Failure | 공통 Failure입니다. 공통 오류 처리를 참조하세요. | 공통 오류 처리 기준에 따라 처리 |
UnknownOutcome | 이 SDK 버전이 알지 못하는 신규 결과입니다. | 실패로 처리하고 결과 코드를 기록 |
단일 우편 상세 조회
GetMailAsync
GetMailAsync()를 호출해 특정 발신 우편의 최신 상태와 본문, 첨부 아이템 정보를 확인합니다. 이미 알고 있는 MailId를 기준으로 단일 우편의 상태를 바로 확인할 때 사용합니다. 발송 직후 상태를 다시 보거나 회수 뒤 Revoked 반영 여부를 확인할 때도 이 메서드를 사용할 수 있습니다.
호출 파라미터
| 필드명 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
request | GetMailRequest | Required | 조회할 발신 우편을 지정하는 요청 |
context | ApiCallContext? | Optional | 호출 단위 설정 객체입니다. 생략하면 기본값이 사용됩니다. |
GetMailRequest
| 필드명 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
MailId | string | Required | 조회할 발신 우편 식별자 |
호출 예시
MailboxGetMailResult의 성공 결과와 이 메서드의 도메인별 결과(Outcome)는 아래 예시와 응답 상태에서 확인합니다. 요청을 수행할 수 없을 때 반환하는 공통 실패(Failure)의 결과 모델과 처리 원칙은 공통 오류 처리를 참조하세요.
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($"처리되지 않은 결과: {result.GetType().Name}");
break;
}
응답 데이터
성공 시 MailboxGetMailResult.Success의 Data(MailResponseData)에 결과가 담깁니다. 발신 우편 상태와 만료 시각, 첨부 아이템 유무를 함께 확인해 운영 상태를 판단합니다.
Data.MailCategory를 제외한 모든 필드가 null을 담을 수 있는 형식으로 선언되어 있으므로, 값을 화면에 표시하거나 다음 호출에 넘기기 전에 null인지 먼저 확인하세요.
| 필드명 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
Data.MailId | string? | Optional | 발신 우편 식별자 |
Data.MailCategory | string | Required | 우편함 카테고리. 발송할 때 카테고리를 지정하지 않았으면 "DEFAULT" |
Data.MailContentType | MailMailContentType? | Optional | 우편 본문 유형 |
Data.SenderType | MailSenderType? | Optional | 발신자 유형 |
Data.SenderId | string? | Optional | 발신자 식별자 |
Data.SenderDisplayName | string? | Optional | 우편 화면에 표시하는 발신자 이름 |
Data.RecipientScope | MailRecipientScope? | Optional | 수신 대상 범위. Broadcast 또는 Direct |
Data.Title | string? | Optional | 우편 제목 |
Data.Body | string? | Optional | 우편 본문 |
Data.Language | LanguageCode? | Optional | 우편 언어 |
Data.MailExtension | string? | Optional | 앱에서 정의한 우편 정책 문자열. 우편 노출 조건이나 수령 조건 등 앱 정책 정보를 저장할 때 사용. 서버는 이 값을 해석하지 않고 그대로 저장 |
Data.ExpiresAt | DateTimeOffset? | Optional | 우편 만료 시각 |
Data.MailStatus | MailMailStatus? | Optional | 현재 발신 우편 상태. Active, Revoked, Expired |
Data.ClosedAt | DateTimeOffset? | Optional | 우편 종료 시각. 우편 상태가 Expired 또는 Revoked로 변경된 UTC 시각. Active 상태일 때는 null |
Data.CreatedAt | DateTimeOffset? | Optional | 우편 생성 시각 |
Data.RecipientPlayerIds | IReadOnlyList<long>? | Optional | 수신자 Player ID 목록. 모든 사용자에게 보낸 우편이면 null |
Data.Attachments | IReadOnlyList<MailAttachment>? | Optional | 첨부 아이템 목록. MailContentType이 Text인 우편은 null이거나 비어 있음 |
MailAttachment
MailAttachment는 Data.Attachments의 각 항목입니다. 발송 시 전달한 AttachmentItem에 대응하며, 앱은 이 값을 읽어 어떤 첨부 아이템을 몇 개 보냈는지 확인합니다.
| 필드명 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
AttachmentType | string? | Optional | 앱에서 정의한 첨부 아이템 타입 |
ReferenceId | string? | Optional | 첨부 아이템 참조 ID |
Quantity | int? | Optional | 지급 수량 |
MailId | string? | Optional | 첨부 아이템이 속한 발신 우편 식별자 |
CreatedAt | DateTimeOffset? | Optional | 첨부 아이템이 생성된 UTC 시각 |
응답 예시
// success.Data 가 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}");
응답 상태
반환 객체 MailboxGetMailResult는 아래 케이스 중 하나로 분기됩니다. switch 구문으로 처리를 권장합니다.
| 응답 케이스 | 설명 | 앱 클라이언트 대응 |
|---|---|---|
Success | 단일 우편 상세 조회 성공. Data에 우편 상세가 담깁니다. | 우편 상태와 만료 시각 등 최신 정보 반영 |
Failure | 공통 Failure입니다. 공통 오류 처리를 참조하세요. | 공통 오류 처리 기준에 따라 처리 |
UnknownOutcome | 이 SDK 버전이 알지 못하는 신규 결과입니다. | 실패로 처리하고 결과 코드를 기록 |
발신 우편 상태를 추적할 때는 상황에 맞게 목록 조회와 상세 조회를 선택해 사용합니다. 전체 현황이나 여러 건의 이력을 확인할 때는 목록 조회를, 특정 우편의 MailStatus와 ExpiresAt을 바로 확인할 때는 상세 조회를 사용합니다.