우편 회수

RevokeMailAsync()를 호출해 이미 발송한 우편을 회수합니다. 발신 우편의 MailId를 확인하고, 필요하면 회수 요청 뒤 상태를 다시 조회해 Revoked로 바뀌었는지 확인합니다.

1. 회수할 우편 식별자 확인

회수 요청에는 발신 우편 식별자인 MailId가 필요합니다. 발송 시 저장한 MailId를 그대로 사용할 수 있고, 회수할 우편이 맞는지 최신 상태와 만료 시각을 함께 점검해야 하면 발신 우편 정보 조회로 다시 확인합니다.

MailId 확인

회수에 사용하는 값은 발신 우편의 MailId입니다. 수신 우편의 MailRecipientId와는 다른 값이므로 혼동하지 않도록 주의합니다.

2. 우편 회수 요청

RevokeMailAsync

RevokeMailAsync()를 호출하면 요청이 접수되면서 발신 우편 상태가 즉시 Revoked로 변경됩니다.

수신 우편 회수는 비동기로 처리합니다. 이미 읽음 처리되었거나 첨부 아이템 수령 상태가 반영된 우편은 회수하지 않습니다.

호출 파라미터

필드명	타입	필수 여부	설명
`request`	`RevokeMailRequest`	Required	회수할 우편을 지정하는 요청
`context`	`ApiCallContext?`	Optional	호출 단위 설정 객체입니다. 생략하면 기본값이 사용됩니다.

RevokeMailRequest

필드명	타입	필수 여부	설명
`MailId`	`string`	Required	회수할 발신 우편의 식별자

호출 예시

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

Unity

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

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

var result = await mailbox.RevokeMailAsync(new RevokeMailRequest {
    MailId = storedMailId,
});

switch (result)
{
    case MailboxRevokeMailResult.Success success:
        AcceptedResponseData data = success.Data;
        Debug.Log($"회수 접수: {data.MailId} (접수 시각: {data.AcceptedAt})");
        break;

    case MailboxRevokeMailResult.Failure failure:
        HiveError err = failure.Problem;
        Debug.LogError($"[{err.Code}] {err.Message} (trace: {err.TraceId})");
        break;

    default:
        Debug.LogWarning($"처리되지 않은 결과: {result.GetType().Name}");
        break;
}

응답 데이터

성공 시 MailboxRevokeMailResult.Success의 Data(AcceptedResponseData)에 결과가 담깁니다. 회수 요청도 발송과 마찬가지로 비동기 접수 형태로 반환됩니다.

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

필드명	타입	필수 여부	설명
`Data.MailId`	`string?`	Optional	회수 요청이 접수된 우편 식별자
`Data.AcceptedAt`	`DateTimeOffset?`	Optional	회수 요청이 접수된 시각

응답 예시

Unity

// success.Data (AcceptedResponseData)
string? mailId = success.Data.MailId;
DateTimeOffset? acceptedAt = success.Data.AcceptedAt;

응답 상태

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

응답 케이스	설명	앱 클라이언트 대응
`Success`	회수 요청이 접수되었습니다. 발신 우편은 즉시 `Revoked`로 변경되고 수신 우편 회수는 비동기로 처리됩니다.	회수 접수 안내 후 필요 시 상태 재조회
`Failure`	공통 Failure입니다. 공통 오류 처리를 참조하세요.	공통 오류 처리 기준에 따라 처리
`UnknownOutcome`	이 SDK 버전이 알지 못하는 신규 결과입니다.	실패로 처리하고 결과 코드를 기록

3. 회수 뒤 상태 재조회

발신 우편 상태가 Revoked로 바뀌었는지는 같은 MailId로 발신 우편 정보 조회를 다시 실행해 확인합니다. 수신자 측 회수가 반영되면 해당 수신 우편은 수신 우편 목록 조회 결과에서 사라집니다. 수신자 화면을 함께 보여 주는 앱이라면 목록을 다시 조회해 우편함 UI를 갱신하는 것을 권장합니다. 회수된 우편은 발신 우편 삭제를 별도로 호출하지 않아도 90일 뒤에 자동으로 완전 삭제(HARD DELETE)됩니다.