---
title: Upload Message
framework: retentionmessaging
role: symbol
role_heading: Web Service Endpoint
path: retentionmessaging/upload-message
---

# Upload Message

Uploads a message to use for retention messaging.

## URL

PUT https://api.storekit.apple.com/inApps/v1/messaging/message/{messageIdentifier}

## Sandbox URL

PUT https://api.storekit-sandbox.apple.com/inApps/v1/messaging/message/{messageIdentifier}

## Path Parameters

messageIdentifier: A UUID you provide to uniquely identify the message you upload.

## Response Codes

200 OK: Request succeeded. 400 Bad Request: The request is invalid and unacceptable. 401 Unauthorized: The JSON Web Token (JWT) in the authorization header is invalid. For more information, see Generating JSON Web Tokens for API requests. 403 Forbidden: The request is forbidden because the system reached the maximum number of uploaded messages. 409 Conflict: The message identifier already exists. 429 : The request exceeded the rate limit. For more information, see Identifying rate limits. 500 Internal Server Error: Server error. Try again later.

## Mentioned in

Setting up retention messages Identifying rate limits

## Discussion

Discussion Call this endpoint to upload the text for retention messages. You provide a unique messageIdentifier to identify each message you upload. You can optionally include an image and bullet points with the message. You define a message by providing the following strings and objects in the UploadMessageRequestBody: The body, which contains the main text of the message. A header, which contains text to display above the message body or above the image. An optional UploadMessageImage that represents an image you upload with alternative text. An optional array of BulletPoint text, along with images to use as the bullet point icons. important: Only text-based retention messages can include images. If you’re uploading text for a promotional-offer message or a switch-plan message, don’t include an image. To change the position of the header text in a retention message, use headerPosition to indicate whether to place the header above the message body or above the image. Each string needs to be a UTF-8-encoded value with a maximum length as indicated below:  |  |   |  |   |  |   |  |   |  |  The maximum number of messages you can configure for each app is 2000. For example, you may choose to upload a message for a product identifier for each locale your app supports. The endpoint returns a MaximumNumberOfMessagesReachedError response if you exceed the maximum limit. Call Delete Message to delete messages. tip: Keep a record of the message and image contents on your system. This endpoint isn’t idempotent. If you have a previously configured message with the same messageIdentifier, the endpoint returns MessageAlreadyExistsError. Determine whether a message is ready to display Immediately after you upload an message, its messageState is PENDING. Apple checks the message, and sets the message state to APPROVED to indicate the system can display it in retention messaging. Call the Get Message List endpoint to check the current state of all messages. If a message includes an image, call Get Image List to check the current state of the image separately. Both the message and its image, if any, need to be in an APPROVED state before the system can display a message. In the sandbox testing environment, the system automatically sets message and image states to APPROVED.

## HTTP Body

The message text to upload.

## See Also

### Message configuration

- [Delete Message](retentionmessaging/delete-message.md)
- [Get Message List](retentionmessaging/get-message-list.md)
- [UploadMessageRequestBody](retentionmessaging/uploadmessagerequestbody.md)
- [UploadMessageImage](retentionmessaging/uploadmessageimage.md)
- [GetMessageListResponse](retentionmessaging/getmessagelistresponse.md)
- [GetMessageListResponseItem](retentionmessaging/getmessagelistresponseitem.md)