# Upload Image Uploads an image to use for retention messaging. ## Discussion Call this endpoint to upload an image that you can associate with a message or a bullet point within the message. You provide a unique `imageIdentifier` to identify each image you upload. You can upload image files that meet the following requirements: - Format: PNG - Doesn’t have transparency > Note: Ensure the images you upload work equally well with both light and dark modes. The maximum number of images you can configure for each app is 2000. The endpoint returns a `MaximumNumberOfImagesReachedError` response if an attempt to upload an image exceeds this limit. Call [`Delete Image`](/documentation/RetentionMessaging/Delete-Image) to delete images. Use full-size images for a message, or the smaller bullet point-size images to use as bullet points. ### Upload full-size images A full-size image is up to 3840 × 2160 pixels, where the width must be 3840 pixels, and the height can be between 160 to 2160 pixels. You can add alternative text for images when you call [`Upload Message`](/documentation/RetentionMessaging/Upload-Message) and associate an image with a message using [`UploadMessageImage`](/documentation/RetentionMessaging/UploadMessageImage). ### Upload images for bullet points Images you use for bullet points are 1024 x 1024 pixels. You can add alternative text for the bullet point images when you supply `bulletPoints` in the [`UploadMessageRequestBody`](/documentation/RetentionMessaging/UploadMessageRequestBody). > Note: This endpoint isn’t idempotent. If you attempt to upload an image and reuse a previously configured `imageIdentifier`, the endpoint returns the ``doc://com.apple.retentionmessaging/documentation/RetentionMessaging/ImageAlreadyExistsError`` response. ### Determine whether an image is ready to display Immediately after you upload an image, its [`imageState`](/documentation/RetentionMessaging/imageState) is `PENDING`. Apple checks the images, and sets the image state to `APPROVED` to indicate the system can display them in retention messaging. Call the [`Get Image List`](/documentation/RetentionMessaging/Get-Image-List) endpoint to check the current state of images you upload. In the sandbox testing environment, the system automatically sets the message and image states to `APPROVED`. --- Copyright © 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)