IMailboxService

앱의 우편함 기능을 Hive Axyl 서버에서 처리하는 서비스입니다. 로그인한 사용자를 기준으로 우편 발송과 회수, 발신 우편과 수신 우편 조회, 수신 우편의 읽음 처리, 우편 삭제를 제공합니다.

• 인터페이스: IMailboxService
• 네임스페이스: Hive.Axyl.Mailbox
• 패키지: com.com2usplatform.hiveaxyl.mailbox

등록과 획득

Unity

using Hive.Axyl.Core;
using Hive.Axyl.Core.Unity;   // HiveBootstrap
using Hive.Axyl.Mailbox;

var config = CoreConfig.CreateBuilder("{appId}").Build();

HiveBootstrap.Initialize(config, builder =>
{
    builder.AddMailbox();
});

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

메서드 요약

'인증' 열의 의미는 인증 요구 표기를 참조하세요.

발신 우편

메서드	인증	설명
SendMailAsync	세션 필요	우편 발송을 요청합니다.
GetSentMailsAsync	세션 필요	발송한 우편 목록을 조회합니다.
GetMailAsync	세션 필요	발송한 우편 하나의 상세 정보를 조회합니다.
RevokeMailAsync	세션 필요	발송한 우편의 회수를 요청합니다.
DeleteSentMailAsync	세션 필요	발송한 우편을 삭제합니다.

수신 우편

메서드	인증	설명
GetReceivedMailsAsync	세션 필요	받은 우편 목록을 조회합니다.
GetReceivedMailAsync	세션 필요	받은 우편 하나의 상세 정보를 조회합니다.
MarkMailAsReadAsync	세션 필요	받은 우편의 본문이나 첨부 아이템을 읽음 처리합니다.
DeleteReceivedMailAsync	세션 필요	받은 우편을 삭제합니다.

공통 파라미터

모든 메서드의 마지막 파라미터는 ApiCallContext? context = null입니다. 생략하면 기본값이 적용됩니다. 자세한 내용은 호출 컨텍스트를 참조하세요.

모든 메서드는 요청 본문을 request 파라미터로 받으며, request는 Required입니다. 아래 메서드 설명에서는 요청 타입만 표기하고 파라미터 표는 생략합니다. 각 요청 타입의 필드는 데이터 타입에서 확인하세요.

발생 예외

• ArgumentNullException: request가 null인 경우

공통 Failure 코드

아래 코드는 서버가 코드로 응답하지만 기능 관점의 결과가 아니므로 Outcome이 아닌 Failure로 분기합니다. 원인 코드는 Failure.Problem.ExternalCode에 담깁니다. 결과 갈래와 분기 방법은 Core 결과 모델을 참조하세요.

• bad_request: 잘못된 요청
• invalid_parameter: 요청 파라미터 형식 오류
• missing_field: 필수 필드나 X-App-Id 같은 필수 헤더 자체의 누락
• missing_app_id: X-App-Id 헤더를 보냈지만 값이 빈 경우
• unauthorized: 인증 토큰이 없거나 유효하지 않은 경우
• token_expired: 인증 토큰 만료
• forbidden: 요청 권한 없음
• resource_not_found: 요청한 리소스 없음
• method_not_allowed: 허용되지 않은 요청 방식
• resource_conflict: 요청과 리소스 상태의 충돌
• unprocessable_content: 처리할 수 없는 요청 내용
• rate_limit_exceeded: 허용 한도를 넘은 요청 빈도
• internal_error: 서버 내부 오류
• service_unavailable: 서비스 일시 중단

메서드

SendMailAsync

우편 발송을 요청합니다. 제목, 본문, 만료 시각, 수신 대상, 첨부 아이템을 담아 우편을 만들며, 서버는 요청을 접수한 뒤 비동기로 처리합니다. 응답의 MailId는 발송한 우편을 GetMailAsync로 조회하거나 RevokeMailAsync로 회수하거나 DeleteSentMailAsync로 삭제할 때 사용하므로 저장하세요.

첨부 아이템은 앱의 아이템, 재화, 쿠폰 같은 콘텐츠를 식별하는 참조 정보입니다. 우편함은 첨부 아이템을 실제로 지급하거나 수령 처리하지 않으므로, 첨부 내용의 검증과 지급은 앱 서버가 처리합니다.

로그인 세션으로 호출할 때는 모든 사용자에게 보내는 Broadcast를 수신 대상 범위로 지정할 수 없습니다. 지정하면 BroadcastMailNotAllowedForUser로 분기하므로 Direct로 수신자를 지정하세요.

SDK는 발송 요청마다 멱등 키를 Idempotency-Key 헤더로 보내며, 전송 계층이 요청을 재시도할 때는 같은 키를 유지합니다. 서버는 멱등 키와 요청 본문이 모두 같은 요청을 60분 동안 중복 요청으로 처리합니다. context를 생략하거나 호출할 때마다 새 ApiCallContext를 만들면 호출마다 다른 키가 전송되므로, 같은 우편을 다시 요청해도 별개의 우편으로 발송됩니다. 앱이 발송을 재시도할 때는 처음과 같은 요청 객체를 다시 전달하고 ApiCallContext.IdempotencyKey에 처음과 같은 키를 지정하세요. 요청 본문이 다르면 중복 요청으로 처리되지 않습니다.

Unity

Task<MailboxSendMailResult> SendMailAsync(SendMailRequest request, ApiCallContext? context = null);

• 요청: SendMailRequest
• 응답: AcceptedResponseData
• 인증: 세션 필요

결과 케이스 — MailboxSendMailResult

결과 케이스	와이어 코드	설명
Success	—	서버가 발송 요청을 접수했습니다. 우편 ID는 Data.MailId에 담깁니다.
BroadcastMailNotAllowedForUser	broadcast_mail_not_allowed_for_user	로그인 세션으로는 모든 사용자에게 보내는 우편을 발송할 수 없습니다.
UnknownOutcome	UNKNOWN	이 SDK 버전이 알지 못하는 새 결과입니다.
Failure	FAILURE	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

구현 절차는 우편 발송과 중복 발송 방지를 참조하세요.

---

GetSentMailsAsync

로그인한 사용자가 발송한 우편 목록을 조회합니다. 카테고리, 본문 유형, 우편 상태로 조회 대상을 거를 수 있습니다. 발송 이력을 확인할 수 있도록 만료되거나 회수된 우편도 포함하며, 삭제한 우편은 제외합니다.

목록은 커서를 기준으로 다음 페이지 방향으로만 조회합니다. 응답의 Data.Meta.Page.NextCursor를 다음 요청의 Cursor에 넣어 다음 페이지를 조회하며, 이전 페이지 커서는 제공하지 않습니다. MailCategory를 지정하지 않으면 기본값인 DEFAULT 카테고리의 우편만 조회합니다.

Unity

Task<MailboxGetSentMailsResult> GetSentMailsAsync(GetSentMailsRequest request, ApiCallContext? context = null);

• 요청: GetSentMailsRequest
• 응답: SentMailListResponseData
• 인증: 세션 필요

결과 케이스 — MailboxGetSentMailsResult

결과 케이스	와이어 코드	설명
Success	—	조회에 성공했습니다.
UnknownOutcome	UNKNOWN	이 SDK 버전이 알지 못하는 새 결과입니다.
Failure	FAILURE	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

구현 절차는 발신 우편 목록 조회를 참조하세요.

---

GetMailAsync

발송한 우편 하나의 상세 정보를 조회합니다. 우편 기본 정보와 첨부 아이템을 함께 반환하며, 삭제한 우편은 조회할 수 없습니다.

Unity

Task<MailboxGetMailResult> GetMailAsync(GetMailRequest request, ApiCallContext? context = null);

• 요청: GetMailRequest
• 응답: MailResponseData
• 인증: 세션 필요

결과 케이스 — MailboxGetMailResult

결과 케이스	와이어 코드	설명
Success	—	조회에 성공했습니다.
UnknownOutcome	UNKNOWN	이 SDK 버전이 알지 못하는 새 결과입니다.
Failure	FAILURE	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

구현 절차는 단일 우편 상세 조회를 참조하세요.

---

RevokeMailAsync

발송한 우편의 회수를 요청합니다. 우편 상태가 Revoked로 바뀌며, 수신자에게 전달된 우편 중 아직 읽지 않은 우편만 회수됩니다. 수신자 우편함에서의 회수는 서버가 비동기로 처리합니다.

Unity

Task<MailboxRevokeMailResult> RevokeMailAsync(RevokeMailRequest request, ApiCallContext? context = null);

• 요청: RevokeMailRequest
• 응답: AcceptedResponseData
• 인증: 세션 필요

결과 케이스 — MailboxRevokeMailResult

결과 케이스	와이어 코드	설명
Success	—	서버가 회수 요청을 접수했습니다.
UnknownOutcome	UNKNOWN	이 SDK 버전이 알지 못하는 새 결과입니다.
Failure	FAILURE	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

구현 절차는 우편 회수를 참조하세요.

---

DeleteSentMailAsync

발송한 우편을 삭제 상태로 바꿉니다. 삭제한 우편은 발신 우편 목록과 상세 조회에서 제외됩니다.

Unity

Task<MailboxDeleteSentMailResult> DeleteSentMailAsync(DeleteSentMailRequest request, ApiCallContext? context = null);

• 요청: DeleteSentMailRequest
• 응답: DeletedSentMailResponseData
• 인증: 세션 필요

결과 케이스 — MailboxDeleteSentMailResult

결과 케이스	와이어 코드	설명
Success	—	우편을 삭제했습니다.
UnknownOutcome	UNKNOWN	이 SDK 버전이 알지 못하는 새 결과입니다.
Failure	FAILURE	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

구현 절차는 발신 우편 삭제를 참조하세요.

---

GetReceivedMailsAsync

로그인한 사용자가 받은 우편 목록을 조회합니다. 카테고리, 본문 유형, 읽음 상태로 조회 대상을 거를 수 있고, 제목은 요청한 언어로 반환합니다. 만료되거나 회수되거나 삭제된 우편은 제외합니다.

목록은 커서를 기준으로 앞뒤 양방향으로 조회합니다. 응답의 Data.Meta.Page.NextCursor나 PreviousCursor를 다음 요청의 Cursor에 넣고 Direction으로 방향을 지정합니다. MailCategory, MailContentType, TextRead, AttachmentRead는 지정하지 않으면 해당 조건 없이 조회합니다.

Unity

Task<MailboxGetReceivedMailsResult> GetReceivedMailsAsync(GetReceivedMailsRequest request, ApiCallContext? context = null);

• 요청: GetReceivedMailsRequest
• 응답: ReceivedMailListResponseData
• 인증: 세션 필요

결과 케이스 — MailboxGetReceivedMailsResult

결과 케이스	와이어 코드	설명
Success	—	조회에 성공했습니다.
UnknownOutcome	UNKNOWN	이 SDK 버전이 알지 못하는 새 결과입니다.
Failure	FAILURE	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

구현 절차는 수신 우편 목록 조회를 참조하세요.

---

GetReceivedMailAsync

받은 우편 하나의 상세 정보를 조회합니다. 우편 기본 정보, 읽음 상태, 첨부 아이템을 함께 반환하며, 제목과 본문은 요청한 언어로 반환합니다. 요청한 언어의 번역이 없으면 우편의 기본 언어로 반환합니다.

조회해도 읽음 상태는 바뀌지 않습니다. 본문이나 첨부 아이템의 읽음 처리는 MarkMailAsReadAsync로 따로 요청하세요. 만료되거나 회수되거나 삭제된 우편은 조회할 수 없습니다.

Unity

Task<MailboxGetReceivedMailResult> GetReceivedMailAsync(GetReceivedMailRequest request, ApiCallContext? context = null);

• 요청: GetReceivedMailRequest
• 응답: MailRecipientResponseData
• 인증: 세션 필요

결과 케이스 — MailboxGetReceivedMailResult

결과 케이스	와이어 코드	설명
Success	—	조회에 성공했습니다.
UnknownOutcome	UNKNOWN	이 SDK 버전이 알지 못하는 새 결과입니다.
Failure	FAILURE	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

구현 절차는 수신 우편 상세 정보 조회를 참조하세요.

---

MarkMailAsReadAsync

받은 우편의 본문이나 첨부 아이템을 읽음 처리합니다. Target에 따라 본문 읽음 시각이나 첨부 아이템 읽음 시각을 기록하며, 여러 번 호출해도 처음 기록한 시각이 유지됩니다.

본문 읽음 시각과 첨부 아이템 읽음 시각은 이 메서드로 기록하기 전까지 null입니다. 우편을 조회해도 읽음 시각은 기록되지 않으므로, 기록할 시점은 앱이 정합니다. 처리 흐름은 읽음과 수령 상태 구분을 참조하세요.

Unity

Task<MailboxMarkMailAsReadResult> MarkMailAsReadAsync(MarkMailAsReadRequest request, ApiCallContext? context = null);

• 요청: MarkMailAsReadRequest
• 응답: MarkMailResponseData
• 인증: 세션 필요

결과 케이스 — MailboxMarkMailAsReadResult

결과 케이스	와이어 코드	설명
Success	—	읽음 처리했습니다. 기록된 시각은 Data.TextReadAt과 Data.AttachmentReadAt에서 확인합니다.
UnknownOutcome	UNKNOWN	이 SDK 버전이 알지 못하는 새 결과입니다.
Failure	FAILURE	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

구현 절차는 우편 읽음 처리를 참조하세요.

---

DeleteReceivedMailAsync

받은 우편을 사용자의 우편함에서 삭제 상태로 바꿉니다. 만료 여부와 관계없이 삭제할 수 있습니다.

Unity

Task<MailboxDeleteReceivedMailResult> DeleteReceivedMailAsync(DeleteReceivedMailRequest request, ApiCallContext? context = null);

• 요청: DeleteReceivedMailRequest
• 응답: DeletedReceivedMailResponseData
• 인증: 세션 필요

결과 케이스 — MailboxDeleteReceivedMailResult

결과 케이스	와이어 코드	설명
Success	—	우편을 삭제했습니다.
UnknownOutcome	UNKNOWN	이 SDK 버전이 알지 못하는 새 결과입니다.
Failure	FAILURE	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

구현 절차는 수신 우편 삭제를 참조하세요.

데이터 타입

여러 타입이 공유하는 필드는 의미가 같습니다. 시각 필드는 모두 UTC 기준입니다.

• MailId: 발송한 우편 하나를 식별하는 ID. 발신 우편의 조회, 회수, 삭제에 사용
• MailRecipientId: 수신자의 우편함에 전달된 우편 하나를 식별하는 ID. 수신 우편의 조회, 읽음 처리, 삭제에 사용
• MailCategory: GROUP, GUILD, EVENT처럼 앱이 정의하는 우편함 카테고리. 우편을 그룹으로 나눠 조회할 때 사용
• SenderDisplayName: 우편 화면에 표시하는 발신자 이름. 발송할 때의 값을 저장하므로 이후 발신자 이름이 바뀌어도 이미 발송한 우편에는 반영되지 않음
• ExpiresAt: 우편이 만료되는 시각. 만료된 우편은 수신 우편 목록과 상세 조회에서 제외되고 발신 우편 목록과 상세 조회에는 포함됨
• Meta: 서버가 가공하지 않은 원본 JSON 문자열로 함께 전달한 부가 정보. 목록 응답의 Meta는 페이지 정보인 MetaPage

AcceptedResponseData

발송 요청과 회수 요청을 서버가 접수했을 때의 응답입니다.

필드	타입	필수 여부	설명
MailId	string?	Optional	요청을 접수한 우편의 ID입니다.
AcceptedAt	DateTimeOffset?	Optional	서버가 요청을 접수한 시각입니다.
Meta	string?	Optional	서버가 함께 전달한 부가 정보입니다.

AttachmentItem

발송할 우편에 담을 첨부 아이템입니다. 우편함은 첨부 아이템을 지급하지 않으므로, 앱이 콘텐츠를 식별하는 데 필요한 값을 넣습니다.

필드	타입	필수 여부	설명
AttachmentType	string	Optional	아이템, 쿠폰, 재화처럼 앱이 정의하는 첨부 아이템 종류입니다. 기본값은 DEFAULT이며 최대 30자입니다.
ReferenceId	string	Required	앱의 콘텐츠를 식별하는 ID입니다. 최대 100자입니다.
Quantity	int	Required	지급할 수량입니다. 아이템 지급 수량이나 재화 지급량을 나타냅니다.

AxylCursorPagination

커서 기반 목록 조회의 페이지 정보입니다.

필드	타입	필수 여부	설명
NextCursor	string?	Optional	다음 페이지를 조회할 때 요청의 Cursor에 넣는 값입니다.
HasNext	bool?	Optional	다음 페이지가 있으면 true입니다.
PreviousCursor	string?	Optional	이전 페이지를 조회할 때 요청의 Cursor에 넣는 값입니다. GetSentMailsAsync는 이 값을 제공하지 않습니다.
HasPrevious	bool?	Optional	이전 페이지가 있으면 true입니다. 양방향 조회를 지원하지 않는 메서드에서는 null입니다.

DeleteReceivedMailRequest

필드	타입	필수 여부	설명
MailRecipientId	string	Required	삭제할 수신 우편의 ID입니다. 수신 우편 목록의 MailRecipientId를 넣습니다.

DeleteSentMailRequest

필드	타입	필수 여부	설명
MailId	string	Required	삭제할 발신 우편의 ID입니다.

DeletedReceivedMailResponseData

필드	타입	필수 여부	설명
MailRecipientId	string?	Optional	삭제한 수신 우편의 ID입니다.
MailId	string?	Optional	삭제한 수신 우편의 원본 우편 ID입니다.
DeletedAt	DateTimeOffset?	Optional	삭제한 시각입니다.
Meta	string?	Optional	서버가 함께 전달한 부가 정보입니다.

DeletedSentMailResponseData

필드	타입	필수 여부	설명
MailId	string?	Optional	삭제한 발신 우편의 ID입니다.
DeletedAt	DateTimeOffset?	Optional	삭제한 시각입니다.
Meta	string?	Optional	서버가 함께 전달한 부가 정보입니다.

GetMailRequest

필드	타입	필수 여부	설명
MailId	string	Required	조회할 발신 우편의 ID입니다. SendMailAsync 응답이나 발신 우편 목록의 MailId를 넣습니다.

GetReceivedMailRequest

필드	타입	필수 여부	설명
MailRecipientId	string	Required	조회할 수신 우편의 ID입니다. 수신 우편 목록의 MailRecipientId를 넣습니다.
Language	LanguageCode	Required	제목과 본문을 받을 언어입니다. 이 언어의 번역이 없으면 우편의 기본 언어로 반환합니다.

GetReceivedMailsRequest

수신 우편 목록의 조회 조건입니다. 값을 지정한 조건만 적용합니다.

필드	타입	필수 여부	설명
Language	LanguageCode?	Optional	제목을 받을 언어입니다. 이 언어의 번역이 없으면 우편의 기본 언어로 반환합니다.
MailCategory	string?	Optional	조회할 우편함 카테고리입니다. 지정하지 않으면 카테고리 조건을 적용하지 않습니다.
MailContentType	ReceivedMailSearchRequestMailContentType?	Optional	조회할 본문 유형입니다. 지정하지 않으면 본문 유형 조건을 적용하지 않습니다.
TextRead	bool?	Optional	본문 읽음 상태 조건입니다. true이면 본문을 읽은 우편만, false이면 읽지 않은 우편만 조회합니다.
AttachmentRead	bool?	Optional	첨부 아이템 읽음 상태 조건입니다. true이면 첨부 아이템을 읽음 처리한 우편만, false이면 읽음 처리하지 않은 우편만 조회합니다.
Cursor	string?	Optional	조회를 시작할 커서입니다. 이전 응답의 NextCursor 또는 PreviousCursor를 넣으며, 지정하지 않으면 첫 페이지를 조회합니다.
Direction	ReceivedMailSearchRequestDirection?	Optional	조회 방향입니다. 지정하지 않으면 Next로 조회합니다.
Size	int	Optional	한 번에 조회할 우편 수입니다. 1~50 범위이며 기본값은 10입니다.

GetSentMailsRequest

발신 우편 목록의 조회 조건입니다.

필드	타입	필수 여부	설명
MailCategory	string	Optional	조회할 우편함 카테고리입니다. 기본값은 DEFAULT이며 최대 64자입니다.
MailContentType	SentMailSearchRequestMailContentType?	Optional	조회할 본문 유형입니다. 지정하지 않으면 모든 유형을 조회합니다.
MailStatus	SentMailSearchRequestMailStatus?	Optional	조회할 우편 상태입니다. 지정하지 않으면 모든 상태를 조회합니다.
Cursor	string?	Optional	조회를 시작할 커서입니다. 이전 응답의 NextCursor를 넣으며, 지정하지 않으면 첫 페이지를 조회합니다.
Size	int	Optional	한 번에 조회할 우편 수입니다. 1~50 범위이며 기본값은 10입니다.

Mail

우편 정보입니다. MailRecipientResponseData의 Mail로 전달됩니다.

필드	타입	필수 여부	설명
MailId	string?	Optional	우편 ID입니다.
MailCategory	string	Required	우편함 카테고리입니다.
MailContentType	MailMailContentType?	Optional	본문 유형입니다.
SenderType	MailSenderType?	Optional	발신자 유형입니다.
SenderId	string?	Optional	발신자 식별자입니다.
SenderDisplayName	string?	Optional	우편 화면에 표시하는 발신자 이름입니다.
RecipientScope	MailRecipientScope?	Optional	수신 대상 범위입니다.
RecipientPlayerIds	IReadOnlyList<long>?	Optional	우편을 받은 사용자의 Player ID 목록입니다. 모든 사용자에게 발송한 우편이면 null입니다.
Title	string?	Optional	목록과 상세 화면에 표시하는 우편 제목입니다.
Body	string?	Optional	상세 화면에 표시하는 우편 본문입니다.
Language	LanguageCode?	Optional	우편의 기본 언어입니다. 번역이 없을 때 이 언어로 표시합니다.
MailExtension	string?	Optional	앱이 정의한 우편 정책 데이터입니다. 서버는 해석하지 않고 문자열로 저장합니다.
ExpiresAt	DateTimeOffset?	Optional	우편 만료 시각입니다.
MailStatus	MailMailStatus?	Optional	우편 상태입니다.
ClosedAt	DateTimeOffset?	Optional	우편 상태가 Expired 또는 Revoked로 바뀐 시각입니다. 상태가 Active이면 null입니다.
CreatedAt	DateTimeOffset?	Optional	우편을 만든 시각입니다.
Attachments	IReadOnlyList<MailAttachment>?	Optional	첨부 아이템 목록입니다.

MailAttachment

우편에 담긴 첨부 아이템 정보입니다.

필드	타입	필수 여부	설명
MailId	string?	Optional	첨부 아이템이 속한 우편의 ID입니다.
Quantity	int?	Optional	지급할 수량입니다.
AttachmentType	string?	Optional	앱이 정의한 첨부 아이템 종류입니다.
ReferenceId	string?	Optional	앱의 콘텐츠를 식별하는 ID입니다.
CreatedAt	DateTimeOffset?	Optional	첨부 아이템을 만든 시각입니다.

MailRecipientResponseData

GetReceivedMailAsync 응답입니다.

필드	타입	필수 여부	설명
MailRecipientId	string?	Optional	수신 우편의 ID입니다.
Mail	Mail?	Optional	우편 정보입니다. 제목과 본문은 요청한 언어로 담깁니다.
RecipientPlayerId	long?	Optional	우편을 받은 사용자의 Player ID입니다.
DeliveredAt	DateTimeOffset?	Optional	우편이 도착한 시각입니다.
TextReadAt	DateTimeOffset?	Optional	본문을 읽음 처리한 시각입니다. 읽음 처리하지 않았으면 null입니다.
AttachmentReadAt	DateTimeOffset?	Optional	첨부 아이템을 읽음 처리한 시각입니다. 읽음 처리하지 않았으면 null입니다.
ExpiresAt	DateTimeOffset?	Optional	우편 만료 시각입니다.
Meta	string?	Optional	서버가 함께 전달한 부가 정보입니다.

MailResponseData

GetMailAsync 응답입니다. 필드는 Mail과 같고, 서버가 함께 전달한 부가 정보인 Meta가 string? 타입으로 추가됩니다.

MarkMailAsReadRequest

필드	타입	필수 여부	설명
MailRecipientId	string	Required	읽음 처리할 수신 우편의 ID입니다. 수신 우편 목록의 MailRecipientId를 넣습니다.
Target	MarkMailRequestTarget	Required	읽음 처리할 대상입니다.

MarkMailResponseData

필드	타입	필수 여부	설명
MailRecipientId	string?	Optional	읽음 처리한 수신 우편의 ID입니다.
TextReadAt	DateTimeOffset?	Optional	본문을 읽음 처리한 시각입니다. 읽음 처리하지 않았으면 null입니다.
AttachmentReadAt	DateTimeOffset?	Optional	첨부 아이템을 읽음 처리한 시각입니다. 읽음 처리하지 않았으면 null입니다.
Meta	string?	Optional	서버가 함께 전달한 부가 정보입니다.

MetaPage

필드	타입	필수 여부	설명
Page	AxylCursorPagination?	Optional	커서 기반 페이지 정보입니다.

ReceivedMailListItem

수신 우편 목록의 항목입니다.

필드	타입	필수 여부	설명
MailRecipientId	string?	Optional	수신 우편의 ID입니다.
MailId	string?	Optional	원본 우편의 ID입니다.
RecipientPlayerId	long?	Optional	우편을 받은 사용자의 Player ID입니다.
DeliveredAt	DateTimeOffset?	Optional	우편이 도착한 시각입니다.
TextReadAt	DateTimeOffset?	Optional	본문을 읽음 처리한 시각입니다. 읽음 처리하지 않았으면 null입니다.
AttachmentReadAt	DateTimeOffset?	Optional	첨부 아이템을 읽음 처리한 시각입니다. 읽음 처리하지 않았으면 null입니다.
ExpiresAt	DateTimeOffset?	Optional	우편 만료 시각입니다.
MailCategory	string?	Optional	우편함 카테고리입니다.
MailContentType	ReceivedMailListItemMailContentType?	Optional	본문 유형입니다.
Title	string?	Optional	목록 화면에 표시하는 우편 제목입니다.
SenderId	string?	Optional	발신자 식별자입니다.
SenderType	ReceivedMailListItemSenderType?	Optional	발신자 유형입니다.
SenderDisplayName	string?	Optional	우편 화면에 표시하는 발신자 이름입니다.

ReceivedMailListResponseData

GetReceivedMailsAsync 응답입니다.

필드	타입	필수 여부	설명
Items	IReadOnlyList<ReceivedMailListItem>	Required	수신 우편 목록입니다.
Meta	MetaPage?	Optional	페이지 정보입니다.

RevokeMailRequest

필드	타입	필수 여부	설명
MailId	string	Required	회수할 발신 우편의 ID입니다. SendMailAsync 응답이나 발신 우편 목록의 MailId를 넣습니다.

SendMailRequest

우편 발송 요청입니다.

필드	타입	필수 여부	설명
MailCategory	string	Optional	우편함 카테고리입니다. 기본값은 DEFAULT이며 최대 64자입니다.
SenderDisplayName	string	Required	우편 화면에 표시할 발신자 이름입니다. 최대 100자입니다.
RecipientScope	SendMailRequestRecipientScope	Required	수신 대상 범위입니다. 로그인 세션으로 호출할 때는 Direct를 지정합니다.
RecipientPlayerIds	IReadOnlyList<long>?	Optional	우편을 받을 사용자의 Player ID 목록입니다. RecipientScope가 Direct이면 필수이며, 최대 100개입니다.
MailContentType	SendMailRequestMailContentType	Required	본문 유형입니다. 첨부 아이템을 함께 보내려면 Attachment를 지정합니다.
Title	string	Required	목록과 상세 화면에 표시할 우편 제목입니다. 최대 300자입니다.
Body	string	Required	상세 화면에 표시할 우편 본문입니다. 최대 1000자입니다.
Language	LanguageCode	Required	제목과 본문을 작성한 언어입니다. 우편의 기본 언어가 되며, 수신자 언어의 제목과 본문이 없으면 이 언어로 표시합니다.
MailExtension	string?	Optional	노출 조건이나 수령 조건처럼 앱이 정의하는 우편 정책 데이터입니다. 서버는 해석하지 않고 문자열로 저장합니다. 최대 4096자입니다.
ExpiresAt	DateTimeOffset	Required	우편 만료 시각입니다. 현재 시각부터 30일 이내로 지정합니다.
Attachments	IReadOnlyList<AttachmentItem>?	Optional	첨부 아이템 목록입니다. MailContentType이 Attachment일 때 사용하며, 최대 10개입니다.

SentMailListItem

발신 우편 목록의 항목입니다. 우편 기본 정보와 수신자 요약 정보를 담습니다.

필드	타입	필수 여부	설명
MailId	string?	Optional	우편 ID입니다. 상세 정보는 이 값으로 GetMailAsync를 호출해 조회합니다.
SenderId	string?	Optional	발신자 식별자입니다.
SenderDisplayName	string?	Optional	우편 화면에 표시하는 발신자 이름입니다.
MailCategory	string?	Optional	우편함 카테고리입니다.
MailContentType	SentMailListItemMailContentType?	Optional	본문 유형입니다.
Title	string?	Optional	목록 화면에 표시하는 우편 제목입니다.
MailStatus	SentMailListItemMailStatus?	Optional	우편 상태입니다.
ClosedAt	DateTimeOffset?	Optional	우편 상태가 Expired 또는 Revoked로 바뀐 시각입니다. 상태가 Active이면 null입니다.
ExpiresAt	DateTimeOffset?	Optional	우편 만료 시각입니다.
CreatedAt	DateTimeOffset?	Optional	우편을 발송한 시각입니다.
FirstRecipientPlayerId	long?	Optional	수신자 목록의 첫 번째 Player ID입니다. 전체 수신자는 GetMailAsync로 확인하며, 모든 사용자에게 발송한 우편이면 null입니다.
RecipientCount	long?	Optional	우편을 받은 전체 사용자 수입니다.

SentMailListResponseData

GetSentMailsAsync 응답입니다.

필드	타입	필수 여부	설명
Items	IReadOnlyList<SentMailListItem>	Required	발신 우편 목록입니다.
Meta	MetaPage?	Optional	페이지 정보입니다.

열거형

앱 코드에는 C# 멤버 이름을 입력하세요. 와이어 값은 서버와 주고받는 문자열입니다.

LanguageCode

Hive Axyl이 지원하는 언어 코드입니다.

Push 모듈에도 LanguageCode가 있습니다

Hive.Axyl.Push 네임스페이스에도 같은 이름의 LanguageCode가 있습니다. 한 파일에서 두 네임스페이스를 함께 가져온 뒤 LanguageCode를 그대로 쓰면 어느 타입인지 모호해 컴파일 오류가 발생합니다. 두 타입을 한 파일에서 함께 쓰려면 using PushLanguageCode = Hive.Axyl.Push.LanguageCode;와 using MailboxLanguageCode = Hive.Axyl.Mailbox.LanguageCode;처럼 두 타입에 각각 별칭을 지정하세요.

C# 멤버	와이어 값	설명
Unspecified	LANGUAGE_CODE_UNSPECIFIED	값을 지정하지 않은 기본값입니다. 요청에 사용하지 마세요.
Ko	ko	한국어입니다.
En	en	영어입니다.
Ja	ja	일본어입니다.
ZhHans	zh-Hans	중국어 간체입니다.
ZhHant	zh-Hant	중국어 번체입니다.
De	de	독일어입니다.
Fr	fr	프랑스어입니다.
Ru	ru	러시아어입니다.
It	it	이탈리아어입니다.
Es	es	스페인어입니다.
Pt	pt	포르투갈어입니다.
Pl	pl	폴란드어입니다.
Nl	nl	네덜란드어입니다.
Tr	tr	튀르키예어입니다.
Th	th	태국어입니다.
Id	id	인도네시아어입니다.
Ar	ar	아랍어입니다.
Hi	hi	힌디어입니다.
Vi	vi	베트남어입니다.
Sv	sv	스웨덴어입니다.
Cs	cs	체코어입니다.
Fa	fa	페르시아어입니다.
No	no	노르웨이어입니다.
Uk	uk	우크라이나어입니다.
Ro	ro	루마니아어입니다.
He	he	히브리어입니다.
Ms	ms	말레이어입니다.
Da	da	덴마크어입니다.
El	el	그리스어입니다.
Hu	hu	헝가리어입니다.
Tl	tl	타갈로그어입니다.

본문 유형 열거형

우편의 본문 유형입니다. 사용 위치마다 전용 열거형이 있으며, 모든 본문 유형 열거형은 멤버가 같고 Unspecified의 와이어 값만 열거형마다 다릅니다.

C# 멤버	와이어 값	설명
Unspecified	열거형마다 다릅니다.	값을 지정하지 않은 기본값입니다. 요청에 사용하지 마세요.
Text	TEXT	텍스트만 담은 우편입니다.
Attachment	ATTACHMENT	첨부 아이템을 함께 담은 우편입니다.

열거형	사용 위치	Unspecified 와이어 값
SendMailRequestMailContentType	SendMailRequest.MailContentType	SEND_MAIL_REQUEST_MAIL_CONTENT_TYPE_UNSPECIFIED
SentMailSearchRequestMailContentType	GetSentMailsRequest.MailContentType	SENT_MAIL_SEARCH_REQUEST_MAIL_CONTENT_TYPE_UNSPECIFIED
ReceivedMailSearchRequestMailContentType	GetReceivedMailsRequest.MailContentType	RECEIVED_MAIL_SEARCH_REQUEST_MAIL_CONTENT_TYPE_UNSPECIFIED
MailMailContentType	Mail.MailContentType, MailResponseData.MailContentType	MAIL_MAIL_CONTENT_TYPE_UNSPECIFIED
SentMailListItemMailContentType	SentMailListItem.MailContentType	SENT_MAIL_LIST_ITEM_MAIL_CONTENT_TYPE_UNSPECIFIED
ReceivedMailListItemMailContentType	ReceivedMailListItem.MailContentType	RECEIVED_MAIL_LIST_ITEM_MAIL_CONTENT_TYPE_UNSPECIFIED

우편 상태 열거형

발송한 우편의 현재 상태입니다. 모든 우편 상태 열거형은 멤버가 같고 Unspecified의 와이어 값만 열거형마다 다릅니다.

C# 멤버	와이어 값	설명
Unspecified	열거형마다 다릅니다.	값을 지정하지 않은 기본값입니다. 요청에 사용하지 마세요.
Active	ACTIVE	유효한 우편입니다.
Revoked	REVOKED	회수한 우편입니다.
Expired	EXPIRED	만료된 우편입니다.

열거형	사용 위치	Unspecified 와이어 값
SentMailSearchRequestMailStatus	GetSentMailsRequest.MailStatus	SENT_MAIL_SEARCH_REQUEST_MAIL_STATUS_UNSPECIFIED
MailMailStatus	Mail.MailStatus, MailResponseData.MailStatus	MAIL_MAIL_STATUS_UNSPECIFIED
SentMailListItemMailStatus	SentMailListItem.MailStatus	SENT_MAIL_LIST_ITEM_MAIL_STATUS_UNSPECIFIED

수신 대상 범위 열거형

우편의 수신 대상 범위입니다. 두 열거형은 멤버가 같고 Unspecified의 와이어 값만 다릅니다.

C# 멤버	와이어 값	설명
Unspecified	열거형마다 다릅니다.	값을 지정하지 않은 기본값입니다. 요청에 사용하지 마세요.
Broadcast	BROADCAST	모든 사용자에게 보내는 우편입니다. 로그인 세션으로 발송할 때는 지정할 수 없습니다.
Direct	DIRECT	RecipientPlayerIds에 지정한 사용자에게 보내는 우편입니다.

열거형	사용 위치	Unspecified 와이어 값
SendMailRequestRecipientScope	SendMailRequest.RecipientScope	SEND_MAIL_REQUEST_RECIPIENT_SCOPE_UNSPECIFIED
MailRecipientScope	Mail.RecipientScope, MailResponseData.RecipientScope	MAIL_RECIPIENT_SCOPE_UNSPECIFIED

발신자 유형 열거형

우편을 발송한 주체의 유형입니다. 두 열거형은 멤버가 같고 Unspecified의 와이어 값만 다릅니다.

C# 멤버	와이어 값	설명
Unspecified	열거형마다 다릅니다.	값을 지정하지 않은 기본값입니다.
Admin	ADMIN	운영자가 발송한 우편입니다.
HiveSystem	HIVE_SYSTEM	Hive 시스템이 발송한 우편입니다.
ProjectSystem	PROJECT_SYSTEM	프로젝트 시스템이 발송한 우편입니다.
User	USER	사용자가 발송한 우편입니다.

열거형	사용 위치	Unspecified 와이어 값
MailSenderType	Mail.SenderType, MailResponseData.SenderType	MAIL_SENDER_TYPE_UNSPECIFIED
ReceivedMailListItemSenderType	ReceivedMailListItem.SenderType	RECEIVED_MAIL_LIST_ITEM_SENDER_TYPE_UNSPECIFIED

MarkMailRequestTarget

MarkMailAsReadAsync로 읽음 처리할 대상입니다. 지정한 대상에 따라 기록되는 읽음 시각 필드가 다릅니다.

C# 멤버	와이어 값	설명
Unspecified	MARK_MAIL_REQUEST_TARGET_UNSPECIFIED	값을 지정하지 않은 기본값입니다. 요청에 사용하지 마세요.
Text	TEXT	본문을 읽음 처리해 TextReadAt을 기록합니다.
Attachment	ATTACHMENT	첨부 아이템을 읽음 처리해 AttachmentReadAt을 기록합니다.
All	ALL	본문과 첨부 아이템을 모두 읽음 처리합니다.

ReceivedMailSearchRequestDirection

GetReceivedMailsAsync의 조회 방향입니다.

C# 멤버	와이어 값	설명
Unspecified	RECEIVED_MAIL_SEARCH_REQUEST_DIRECTION_UNSPECIFIED	값을 지정하지 않은 기본값입니다. 요청에 사용하지 마세요.
Previous	PREVIOUS	이전 페이지 방향으로 조회합니다.
Next	NEXT	다음 페이지 방향으로 조회합니다.