Name

Type

Mandatory

Description

Content-Type

String

Y

"application/json;charset=UTF-8"

appSecret

String

Y

App Secret

Authorization

String

Y

Authorization: KakaoAK {ADMIN_KEY}

kgAppId

String

Y

KG App Id

playerId

String

Y

User ID issued by the platform (Item sender)

senderAppId

String

N

Sender App ID (set to appId if left blank)

appId

String

Y

Receiver App ID

senderId

String

Y

Sender ID

receiverId

String

Y

Receiver ID

message

Message

Y

Message

items

List<Item>

N

Item list

checkPlayer

Boolean

N

Whether to check the user

receiverIdType

String

N

User type (default: playerId)

messageId

String

N

Unique message UUID.

• If the same messageId is used in a request, it won't be processed twice.

• It is recommended to generate a messageId.

  • Example: {kgAppId}_{playerId}_{timestamp}

  • If called with an empty value, the platform will automatically generate a UUID.

• If a message registration request is made and a valid response is not received, the previously generated messageId can be used to resend the request.

• The maximum length of messageId is limited to 64 characters.

messageBoxId

String

N

Unique mailbox ID.

• If left blank, the mail will be sent to the default mailbox (inbox).

title

String

N

Title

body

String

N

Body

titleMap

Map<String, String>

N

Title (used for multilingual processing)

bodyMap

Map<String, String>

N

Body (used for multilingual processing)

resourceMap

Map<String, String>

N

Data values required to display the message

Limitations

• 1-dimensional Key-Value

• Maximum of 10 keys

• Each value size is limited to 100 bytes

expiryTime

Long

N

Expiration time. If specified, it must be at least 10 seconds after the registration time.

Cannot exceed the message box's expiration time.

itemCode

String

Y

Item code

quantity

Long

Y

Item quantity

validityTime

Long

N

Validity period.

If not specified, set to -1 (unlimited).

200

Normal response

Normal

400

Bad Request

Unparsable request data, missing required parameters, or parameter type error

401

Unauthenticated

Authentication failed

406

Not Acceptable

Cannot process

461

Invalid Message Box

The requested message box with messageBoxId does not exist.

500

Internal Server Error

Internal server system error

503

Service Unavailable

Service is unavailable (e.g., internal server timeout)

messageId

String

The messageId of the delivered message

Name

Type

Mandatory

Description

Content-Type

String

Y

"application/json;charset=UTF-8"

appSecret

String

Y

App Secret

Authorization

String

Y

Authorization: KakaoAK {ADMIN_KEY}

kgAppId

String

Y

KG App Id

playerId

String

Y

User ID issued by the platform (Item sender)

messageBoxId

String

N

Mailbox Id
- Used to query only a specific message box (Default mailbox if not entered)

count

Integer

Y

Number of messages to retrieve (maximum 100)

nextPageKey

Long

N

Offset to query the starting offset of the page.

If null, the first page is requested.

Even if you enter the Long Max value (9223372036854775807), the first page is requested.

states

List<String>

N

List of message state values to query:

unread, read, error, deleted, expired.

If not entered, a list of messages in unread and read states is returned.

200

Normal Response

Normal

400

Bad Request

Unparsable request data. Lack of required parameters or parameter type error

401

Unauthenticated

Unauthenticated request

406

Not Acceptable

Non-existent user

461

Restricted

Restricted User

463

Removed

Unregistered User (The user has applied to unregister, and the process is ongoing. The actual user data still exists.)

500

Internal Server Error

Internal server system error

503

Service Unavailable

Service is unavailable (e.g., internal server timeout)

nextPageKey

Long

다음 페이지 요청시 사용될

nextPageKey

• -1 이면 더이상 데이터가 없음

messages

List<MessagePacket>

메시지 목록

maxCount

Integer

최대 보유 가능 메시지 개수

totalCount

Integer

현재 메시지 개수 (전체 페이지)

message

Message

메시지 데이터

items

List<Item>

첨부 아이템 목록 

existUnconfirmedItems

Boolean

미확인 아이템 존재 여부

deliverySeq

Long

메시지 고유번호

messageId

String

메시지 ID

messageBoxId

String

우편함 ID

senderAppId

String

발신자 App ID

senderId

String

발신자 ID

receiverAppId

String

수신자 App ID

receiverId

String

수신자 ID

title

String

제목

body

String

본문

resourceMap

Map

메시지를 표현할때 필요한 데이터 값

state

String

메시지 상태 값

unread, read, error, deleted, expired

regTime

Long

등록 시각

modTime

Long

최종 수정 시각

readTime

Long

확인 처리 시각 (읽음 처리)

expiredTime

Long

만료시각

itemId

String

아이템 고유 ID

itemCode

String

아이템 코드

itemName

String

아이템 명

quantity

Long

아이템 수량

state

String

처리 상태값

registered, sent, confirmed, error, deleted, expired

sentCount

Integer

아이템 클레임 처리 횟수

• 2회 이상 클레임 처리 시 이상 동작으로 간주합니다

validityTime

Long

아이템 유효시간

regTime

Long

등록 시각

modTime

Long

최종 수정 시각

sentTime

Long

requestItem 요청 시각

confirmedTime

Long

확인 처리 시각

expiredTime

Long

만료시각

Name

Type

Mandatory

Description

Content-Type

String

Y

"application/json;charset=UTF-8"

appSecret

String

Y

App Secret

Authorization

String

Y

Authorization: KakaoAK {ADMIN_KEY}

kgAppId

String

Y

KG App Id

playerId

String

Y

User ID issued by the platform (Item sender)

messageIds

List<String>

Y

아이템을 수령할 메시지 ID 목록

200

정상 응답

정상

400

Bad Request

파싱되지 않는 요청 데이터. 필수 파라미터 부족 or 파라미터 타입 오류

401

Unauthenticated

인증되지 않은 요청

406

Not Acceptable

존재하지 않는 메시지

500

Internal Server Error

서버 시스템 내부 오류

503

Service Unavailable

서비스가 가능하지 않은 상태 (예, 내부 서버간 timeout)

results

List<Result>

아이템 정보 목록

messageId

String

messageId

status

Integer

아이템 클레임 처리 상태 코드

• 정상 처리 : 200

• 에러 발생 : 406

  • 아이템이 ‘등록된’ 상태가 아닌 경우

  • 이미 ‘클레임’ 처리된 경우

  • 20초 이내로 중복 클레임 처리 요청이 들어온 경우

  • 클레임 횟수가 2번 이상인 경우

receiverId

String

수신자 ID

senderId

String

발신자 ID

resourceMap

Map<String, String>

메시지 표현 시 필요한 값

items

List<Item>

아이템 정보 목록

appId

String

App ID

itemCode

String

아이템 코드

quantity

Long

아이템 수량

itemId

String

아이템 고유 ID

validityTime

Long

유효기한

• 메시지 전송 시점에 해당필드가 비어있으면 -1로 기록 (예: 프로모션 통해서 아이템 전송받은 경우)

senderId

String

발신자 ID

Name

Type

Mandatory

Description

Content-Type

String

Y

"application/json;charset=UTF-8"

appSecret

String

Y

App Secret

Authorization

String

Y

Authorization: KakaoAK {ADMIN_KEY}

kgAppId

String

Y

KG App Id

playerId

String

Y

User ID issued by the platform (Item sender)

messageIds

List<String>

Y

완료 처리할 메시지 ID 목록

200

정상 응답

정상

400

Bad Request

파싱되지 않는 요청 데이터. 필수 파라미터 부족 or 파라미터 타입 오류

401

Unauthenticated

인증되지 않은 요청

406

Not Acceptable

존재하지 않는 메시지

500

Internal Server Error

서버 시스템 내부 오류

503

Service Unavailable

서비스가 가능하지 않은 상태 (예, 내부 서버간 timeout)

results

List<Result>

아이템 정보 목록

messageId

String

messageId

status

Integer

처리 결과 ( 200 성공 )

Name

Type

Mandatory

Description

Content-Type

String

Y

"application/json;charset=UTF-8"

appSecret

String

Y

App Secret

Authorization

String

Y

Authorization: KakaoAK {ADMIN_KEY}

kgAppId

String

Y

KG App Id

playerId

String

Y

User ID issued by the platform (Item sender)

messageIds

List<String>

Y

읽음 처리할 메시지 ID 목록

200

정상 응답

정상

400

Bad Request

파싱되지 않는 요청 데이터. 필수 파라미터 부족 or 파라미터 타입 오류

401

Unauthenticated

인증되지 않은 요청

406

Not Acceptable

존재하지 않는 메시지

500

Internal Server Error

서버 시스템 내부 오류

503

Service Unavailable

서비스가 가능하지 않은 상태 (예, 내부 서버간 timeout)

Name

Type

Mandatory

Description

Content-Type

String

Y

"application/json;charset=UTF-8"

appSecret

String

Y

App Secret

Authorization

String

Y

Authorization: KakaoAK {ADMIN_KEY}

kgAppId

String

Y

KG App Id

playerId

String

Y

User ID issued by the platform (Item sender)

messageIds

List<String>

Y

아이템 지급 완료 처리할 메시지 ID 목록

200

정상 응답

정상

400

Bad Request

파싱되지 않는 요청 데이터. 필수 파라미터 부족 or 파라미터 타입 오류

401

Unauthenticated

인증되지 않은 요청

406

Not Acceptable

존재하지 않는 메시지

500

Internal Server Error

서버 시스템 내부 오류

503

Service Unavailable

서비스가 가능하지 않은 상태 (예, 내부 서버간 timeout)

Name

Type

Mandatory

Description

Content-Type

String

Y

"application/json;charset=UTF-8"

appSecret

String

Y

App Secret

Authorization

String

Y

Authorization: KakaoAK {ADMIN_KEY}

kgAppId

String

Y

KG App Id

playerId

String

Y

User ID issued by the platform (Item sender)

messageIds

List<String>

Y

삭제 처리할 메시지 ID 목록

200

정상 응답

정상

400

Bad Request

파싱되지 않는 요청 데이터. 필수 파라미터 부족 or 파라미터 타입 오류

401

Unauthenticated

인증되지 않은 요청

406

Not Acceptable

존재하지 않는 메시지

500

Internal Server Error

서버 시스템 내부 오류

503

Service Unavailable

서비스가 가능하지 않은 상태 (예, 내부 서버간 timeout)