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

Next page key

to be used for the next page request.

• If -1, there is no more data.

messages

List<MessagePacket>

Message list

maxCount

Integer

• Maximum number of messages that can be stored

totalCount

Integer

Current number of messages (total pages)

message

Message

Message data

items

List<Item>

List of attached items 

existUnconfirmedItems

Boolean

Whether there are unconfirmed items

deliverySeq

Long

Unique message number

messageId

String

Message ID

messageBoxId

String

Mailbox ID

senderAppId

String

Sender App ID

senderId

String

Sender ID

receiverAppId

String

Receiver App ID

receiverId

String

Receiver ID

title

String

Title

body

String

Body

resourceMap

Map

Data values required to represent the message

state

String

Message state value

unread, read, error, deleted, expired

regTime

Long

Registration time

modTime

Long

Last modification time

readTime

Long

Confirmation processing time (read processing)

expiredTime

Long

Expiration time

itemId

String

Unique item ID

itemCode

String

Item code

itemName

String

Item name

quantity

Long

Item quantity

state

String

Processing state value

registered, sent, confirmed, error, deleted, expired

sentCount

Integer

Number of times the item claim has been processed.

• It is considered abnormal operation if claimed more than twice.

validityTime

Long

Item validity time

regTime

Long

Registration time

modTime

Long

Last modification time

sentTime

Long

Time when the requestItem was sent

confirmedTime

Long

Confirmation processing time

expiredTime

Long

Expiration time

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

List of message IDs for which to claim items

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 message

500

Internal Server Error

Internal server system error

503

Service Unavailable

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

results

List<Result>

• List of item information

messageId

String

messageId

status

Integer

Item claim processing status code

• Normal processing: 200

• Error occurred: 406

  • When the item is not in a 'registered' state

  • When the item has already been 'claimed'

  • When a duplicate claim request is made within 20 seconds

  • When the number of claims exceeds 2 times

receiverId

String

Receiver ID

senderId

String

Sender ID

resourceMap

Map<String, String>

Values required to represent the message

items

List<Item>

List of item information

appId

String

App ID

itemCode

String

Item code

quantity

Long

Item quantity

itemId

String

Unique item ID

validityTime

Long

Validity period.

• If this field is empty at the time of message sending, it will be recorded as -1 (e.g., in the case of items sent through promotions).

senderId

String

Sender 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

List of message IDs to be marked as completed

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 message

500

Internal Server Error

Internal server system error

503

Service Unavailable

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

results

List<Result>

List of item information

messageId

String

messageId

status

Integer

Processing result (200 success)

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

List of message IDs to be marked as read

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 message

500

Internal Server Error

Internal server system error

503

Service Unavailable

Service is unavailable (e.g., internal server 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

List of message IDs to be processed for item delivery completion

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 message

500

Internal Server Error

Internal server system error

503

Service Unavailable

Service is unavailable (e.g., internal server 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

List of message IDs to be processed for deletion

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 message

500

Internal Server Error

Internal server system error

503

Service Unavailable

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