<!--
{
  "availability" : [

  ],
  "documentType" : "symbol",
  "framework" : "RetentionMessaging",
  "identifier" : "/documentation/RetentionMessaging/Upload-Message",
  "metadataVersion" : "0.1.0",
  "role" : "Web Service Endpoint",
  "symbol" : {
    "kind" : "Web Service Endpoint",
    "modules" : [
      "Retention Messaging API"
    ],
    "preciseIdentifier" : "rest:retention_messaging:put:inApps-v1-messaging-message-{}"
  },
  "title" : "Upload Message"
}
-->

# Upload Message

Uploads a message to use for retention messaging.

## 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`](/documentation/RetentionMessaging/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`](/documentation/RetentionMessaging/UploadMessageImage) that represents an image you upload with alternative text.
- An optional array of [`BulletPoint`](/documentation/RetentionMessaging/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`](/documentation/RetentionMessaging/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:

|Field                                                                                  |Maximum length|Related error code                                                                                           |
|---------------------------------------------------------------------------------------|-------------:|-------------------------------------------------------------------------------------------------------------|
|``doc://com.apple.retentionmessaging/documentation/RetentionMessaging/header``         |66            |``doc://com.apple.retentionmessaging/documentation/RetentionMessaging/HeaderTooLongError``                   |
|``doc://com.apple.retentionmessaging/documentation/RetentionMessaging/body``           |144           |``doc://com.apple.retentionmessaging/documentation/RetentionMessaging/BodyTooLongError``                     |
|``doc://com.apple.retentionmessaging/documentation/RetentionMessaging/altText``        |150           |``doc://com.apple.retentionmessaging/documentation/RetentionMessaging/AltTextTooLongError``                  |
|``doc://com.apple.retentionmessaging/documentation/RetentionMessaging/bulletPointText``|66            |``doc://com.apple.retentionmessaging/documentation/RetentionMessaging/BadRequestBulletPointTextTooLongError``|

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`](/documentation/RetentionMessaging/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`](/documentation/RetentionMessaging/MessageAlreadyExistsError).

### Determine whether a message is ready to display

Immediately after you upload an message, its [`messageState`](/documentation/RetentionMessaging/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`](/documentation/RetentionMessaging/Get-Message-List) endpoint to check the current state of all messages. If a message includes an image, call [`Get Image List`](/documentation/RetentionMessaging/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`.

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)