--- title: Message API description: "The **Message API** provides resources for managing user conversations on the eBay platform, allowing developers to send, retrieve, and update the status of messages and conversations. Key functionalities include sending messages in new or existing threads (**sendMessage**), retrieving filtered lists of conversations (**getConversations**), fetching all messages within a specific conversation (**getConversation**), and modifying the status (e.g., active, deleted, archived, read, unread) of single or multiple conversations (**updateConversation**, **bulkUpdateConversation**)." api_version: 1.0.0 api_name: message_api api_type: REST api_group: message/api source_url: html: https://developer.ebay.com/develop/api/message/api md: https://developer.ebay.com/develop/api/message/api.md --- # Message API API The **Message API** provides resources for managing user conversations on the eBay platform, allowing developers to send, retrieve, and update the status of messages and conversations. Key functionalities include sending messages in new or existing threads (**sendMessage**), retrieving filtered lists of conversations (**getConversations**), fetching all messages within a specific conversation (**getConversation**), and modifying the status (e.g., active, deleted, archived, read, unread) of single or multiple conversations (**updateConversation**, **bulkUpdateConversation**). ## API Information **Title:** M2M Public API Service **Version:** 1.0.0 **Description:** The eBay Message API provides resources for managing user conversations on the eBay platform, allowing developers to send, retrieve, and update the status of messages and conversations. Key functionalities include sending messages in new or existing threads (sendMessage), retrieving filtered lists of conversations (getConversations), fetching all messages within a specific conversation (getConversation), and modifying the status (e.g., active, deleted, archived, read, unread) of single or multiple conversations (updateConversation, bulkUpdateConversation). **Base Path:** /commerce/message/v1 ## API Methods The following API methods are available: ### bulkUpdateConversation #### POST /bulk_update_conversation **Description:** This method can be used to update the **conversationStatus** of up to 10 conversations. The **conversationId**, existing **conversationType**, and updated **conversationStatus** for each conversation to modify are required in the **conversations** array. **Important!** Although it cannot be updated, the **conversationType** field is required for each conversation being updated. If the updates were successful, the **conversationId** of each conversation will be returned with an associated **updateStatus** value of `SUCCESSFUL`. **Parameters:** - **Content-Type** (string) *required* - This header indicates the format of the request body provided by the client. Its value should be set to **application/json**. **OAuth scope** This request requires an access token created with the **Client Credentials Grant** flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application): **Required Scopes:** **Client Credentials Grant:** - `https://api.ebay.com/oauth/api_scope/commerce.message` ### getConversation #### GET /conversation/{conversation_id} **Description:** This method can be used to retrieve messages within a specific conversation. The **conversation\_id** of the conversation for which to retrieve messages is required as a path parameter and the **conversation\_type** of the conversation is required as a query parameter. **Parameters:** - **conversation_id** (string) *required* - This path parameters specify the unique identifier of the conversation that is to be retrieved. Use the [getConversations](/develop/api/sell/message_api#sell-message_api-conversation-getconversations) method to retrieve conversation ID values. - **conversation_type** (string) *required* - This query parameter specifies the type of the conversation being retrieved. This parameter is always required when using this method. **Valid values:** * `FROM_EBAY` * `FROM_MEMBERS` - **limit** (string) - The maximum number of entries that can be returned on each page of the paginated response. Use this parameter in conjunction with the **offset** parameter to control the pagination of the output. For example, if **offset** is set to `10` and **limit** is set to `10`, the call retrieves entries 11 through 20 from the result set. **Note:** This feature employs a zero-based list, where the first item in the list has an offset of `0`. If this parameter is omitted, the default value is used. **Default:** 25 **Maximum:** 50 - **offset** (string) - The number of reports to skip in the result set before returning the first entry in the paginated response. Use this parameter in conjunction with the **limit** parameter to control the pagination of the output. For example, if **offset** is set to `0` and **limit** is set to `10`, the first page of the response will contain the first 10 entries from the complete list retrieved by the call. **Note:** This feature employs a zero-based list, where the first item in the list has an offset of `0`. If this parameter is omitted, the default value is used. **Default:** 0 **OAuth scope** This request requires an access token created with the **Client Credentials Grant** flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application): **Required Scopes:** **Client Credentials Grant:** - `https://api.ebay.com/oauth/api_scope/commerce.message` ### getConversations #### GET /conversation **Description:** This method can be used to retrieve one or more conversations associated with a user. The **conversation\_type** query parameter is required when using this method to specify if the retrieved conversations are from eBay or from members. The result set can also optionally be filtered by conversation status, reference, username, and/or time range. The **limit** and **offset** path parameters can be used to paginate the result set and control how many conversations are returned in the response. **Parameters:** - **conversation_status** (string) - This query parameter specifies the status of the conversations being retrieved. Only conversations with the specified status will be returned. **Valid values:** * `ACTIVE` * `ARCHIVED` * `DELETED` * `READ` * `UNREAD` - **conversation_type** (string) *required* - This query parameter specifies the type of the conversations being retrieved. Only conversations of the specified type will be returned. This parameter is required when using this method. **Valid values:** * `FROM_EBAY` * `FROM_MEMBERS` - **end_time** (string) - This query parameter specifies the end time (in ISO 8601 format) for which to stop retrieving conversations. For example, if set to `2024-11-06T10:00:00.000Z`, only messages sent before this time will be retrieved. **Format:** yyyy-MM-ddThh:mm.ss.sssZ **Note:** Currently, this parameter is only available if the **conversation\_type** of the conversation is `FROM_MEMBERS`. - **limit** (string) - The maximum number of entries that can be returned on each page of the paginated response. Use this parameter in conjunction with the **offset** parameter to control the pagination of the output. For example, if **offset** is set to `10` and **limit** is set to `10`, the call retrieves entries 11 through 20 from the result set. **Note:** This feature employs a zero-based list, where the first item in the list has an offset of `0`. If this parameter is omitted, the default value is used. **Default:** 25 **Maximum:** 50 - **offset** (string) - The number of reports to skip in the result set before returning the first entry in the paginated response. Use this parameter in conjunction with the **limit** parameter to control the pagination of the output. For example, if **offset** is set to `0` and **limit** is set to `10`, the first page of the response will contain the first 10 entries from the complete list retrieved by the call. **Note:** This feature employs a zero-based list, where the first item in the list has an offset of `0`. If this parameter is omitted, the default value is used. **Default:** 0 - **other_party_username** (string) - This query parameter specifies the username (login name) of an eBay user for which to retrieve conversations. If this filter is used, only conversation(s) from the other eBay user specified through this parameter will be returned. **Note:** Effective September 26, 2025, select developers will no longer receive username data for U.S. users through this field. Instead, an immutable user ID will be returned in its place. For more information, please refer to [Data Handling Compliance](/api-docs/static/data-handling-update.html). - **reference_id** (string) - This query parameter specifies the unique identifier of the reference (specified by the corresponding **reference\_type** value) associated with the conversation. Only conversations associated with the specified reference ID will be returned. For example, in the case of a `LISTING` reference, this value will be the item ID value of the listing. **Note:** If this query parameter is used, the **reference\_type** parameter must also be used to specify the type of reference this ID is associated with. - **reference_type** (string) - This query parameter specifies the type of reference associated with a conversation. The reference type is used to specify what the conversation is in reference to. For example, a value of `LISTING` specifies that the conversation is associated with a specific listing. The item ID associated with this listing can then be specified through the **reference\_id** query parameter. Currently, only the `LISTING` reference type is supported. - **start_time** (string) - This query parameter specifies the start time (in ISO 8601 format) for which to start retrieving conversations. For example, if set to `2024-11-06T10:00:00.000Z`, only messages sent after this time will be retrieved. **Format:** yyyy-MM-ddThh:mm.ss.sssZ **Note:** Currently, this parameter is only available if the **conversation\_type** of the conversation is `FROM_MEMBERS`. **OAuth scope** This request requires an access token created with the **Client Credentials Grant** flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application): **Required Scopes:** **Client Credentials Grant:** - `https://api.ebay.com/oauth/api_scope/commerce.message` ### sendMessage #### POST /send_message **Description:** This method can be used to start a conversation with another user or send a message in an existing conversation with another user based on the information provided in the request. To send a message, one of the **conversationId** or **otherPartyUsername** request fields is required. The **conversationId** must be used when sending a message in an existing conversation and specifies the conversation for which to send the message. For a new conversation, the **otherPartyUsername** field must be used to send the message to a specific user. In addition, the **messageText** field is required as it contains the body text of the message. Optionally, media (such as images or documents) can be attached to the message using the **messageMedia** container. The **reference** container can also be used to associate a message with a listing. **Parameters:** - **Content-Type** (string) *required* - This header indicates the format of the request body provided by the client. Its value should be set to **application/json**. **OAuth scope** This request requires an access token created with the **Client Credentials Grant** flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application): **Required Scopes:** **Client Credentials Grant:** - `https://api.ebay.com/oauth/api_scope/commerce.message` ### updateConversation #### POST /update_conversation **Description:** This method can be used to update the **conversationStatus** or the **read** status of a specified conversation. **Note:** Only one of these statuses can be updated at a time using this method. If both fields are included, only the **read** status of the specified conversation will be updated and the **conversationStatus** field will be ignored. Both the **conversationId** of the conversation to modify and the existing **conversationType** of the specified conversation are required as part of the request payload. **Important!** Although it cannot be updated, the existing **conversationType** of the specified conversation to be updated is required in the request payload. If this value is not provided, an error will occur. To update a conversation's status (e.g., updating an `ACTIVE` conversation to `ARCHIVE`), include the **conversationStatus** field in the request with the updated value. To update a conversation's read status (e.g., updating an `UNREAD` conversation to `READ`), include the **read** boolean in the request with the updated value. **Parameters:** - **Content-Type** (string) *required* - This header indicates the format of the request body provided by the client. Its value should be set to **application/json**. **OAuth scope** This request requires an access token created with the **Client Credentials Grant** flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application): **Required Scopes:** **Client Credentials Grant:** - `https://api.ebay.com/oauth/api_scope/commerce.message` ## Error Codes The following error codes may be returned by this API: ### REQUEST Errors #### 355001 - API_MESSAGE **Description:** Invalid conversationStatus value. Please see documentation for valid values. #### 355002 - API_MESSAGE **Description:** Invalid conversationType value. Please see documentation for valid values. #### 355007 - API_MESSAGE **Description:** Invalid or unrecognized conversation\_id value. #### 355019 - API_MESSAGE **Description:** The number of conversations for batch update exceeds the limit. A maximum of {maximumConversationAllowedCount} conversations is allowed per request. #### 355008 - API_MESSAGE **Description:** Invalid offset. The offset value must be a positive integer value and synchronized up with the limit value. If the limit value is 20, value offset values would be 0, 20, 40, etc. #### 355009 - API_MESSAGE **Description:** Invalid limit. The limit value must be a positive integer value that does not exceed {maximumAllowedLimitNumber}. #### 355003 - API_MESSAGE **Description:** Invalid reference\_type value. Please see documentation for valid values. #### 355004 - API_MESSAGE **Description:** The start\_time must be an earlier date than end\_time. #### 355005 - API_MESSAGE **Description:** Invalid date format used for one or both date filters. Please use ISO 8601 dates with UTC offset. #### 355006 - API_MESSAGE **Description:** Invalid or unrecognized other\_party\_username value. #### 355016 - API_MESSAGE **Description:** Invalid reference\_id. The reference\_id value must be a positive integer value. #### 355017 - API_MESSAGE **Description:** The required conversation\_type query parameter is either missing or has an invalid value. Please include this parameter and use a supported value. #### 355022 - API_MESSAGE **Description:** The parameter reference\_type is required whenever reference\_id is provided. #### 355010 - API_MESSAGE **Description:** The maximum amount of media that may be sent is {maximumMediaAllowedCount}. Please reduce the number of media in the messageMedia array to {maximumMediaAllowedCount} and try again. #### 355011 - API_MESSAGE **Description:** Invalid mediaType value. Please see documentation for valid values. #### 355012 - API_MESSAGE **Description:** All fields under messageMedia are required. Please add missing field(s). #### 355013 - API_MESSAGE **Description:** The messageText string exceeds the maximum character threshold of {maximumMessageTextAllowedLength}. Please modify the message text to meet this requirement. #### 355014 - API_MESSAGE **Description:** Invalid mediaUrl. Please see documentation. #### 355015 - API_MESSAGE **Description:** Please pass message text or upload one or more media attachments. #### 355018 - API_MESSAGE **Description:** conversationId and otherPartyUsername cannot both be empty. #### 355020 - API_MESSAGE **Description:** The referenceId is invalid. No listing can be found for this referenceId. #### 355021 - API_MESSAGE **Description:** All fields under reference are required. Please add missing field(s). ### APPLICATION Errors #### 335000 - API_MESSAGE **Description:** Internal server error encountered. If this problem persists, contact the eBay Developers Program for support. ## Types ### BulkConversation **Description:** This type specifies the conversations to be updated. **Type:** object **Properties:** - **conversationId** (string) - This field indicates the unique identifier of the conversation that is to be updated. Use the [getConversations](/develop/api/sell/message_api#sell-message_api-conversation-getconversations) method to retrieve conversation ID values. - **conversationStatus** (string) - This field indicates the status for which to update the associated conversation. **Valid values:** * `ACTIVE` * `ARCHIVE` * `DELETE` * `READ` * `UNREAD` - **conversationType** (string) - This field specifies the existing type of the conversation that is to be updated. **Important!** This value **cannot** be updated using this method but is required for each conversation being updated. **Valid values:** * `FROM_MEMBERS` * `FROM_EBAY` ### BulkUpdateConversationsRequest **Description:** This type defines the request body of the **bulkUpdateConversation** method. **Type:** object **Properties:** - **conversations** (array) - This array specifies the list of conversations to update and the updated **conversationStatus** for each. ### BulkUpdateConversationsResponse **Description:** This type defines the response payload of the **bulkUpdateConversation** method. **Type:** object **Properties:** - **conversationsMetadata** (ConversationsMetadata) - This container returns metadata from the call, such as how many conversations were updated, how many succeeded, and how many failed. - **conversationsResponse** (array) - This array returns a list of each conversation specified in the request and if the requested update was successful or failed. ### ConversationDetail **Description:** This type defines the details of a conversation, such as its ID, status, type, and latest message. **Type:** object **Properties:** - **conversationId** (string) - The unique identifier of the conversation. - **conversationStatus** (string) - This value indicates the current status of the conversation, such as `ACTIVE` or `ARCHIVED`. - **conversationTitle** (string) - This value indicates the title of the conversation. - **conversationType** (string) - This value indicates the type of the conversation, such as `FROM_EBAY` or `FROM_MEMBERS`. - **createdDate** (string) - This value indicates the date the conversation was created in ISO 8601 format. - **latestMessage** (MessageDetail) - This container returns the latest message in the conversation and its details. - **referenceId** (string) - This value indicates the reference ID associated with the corresponding **referenceType** value. In the case of a `LISTING` **referenceType**, this value will be the item ID value of the associated listing. - **referenceType** (string) - This value indicates the reference type, if applicable, associated with the conversation. The reference type is used to specify what the conversation is in reference to. For example, a value of `LISTING` specifies that the conversation is associated with a specific listing. The item ID associated with this listing will then be returned in the **referenceId** field. Currently, only the `LISTING` reference type is supported. - **unreadCount** (integer) - This value indicates the number of unread messages in the conversation. ### ConversationsMetadata **Description:** This type defines the metadata, such as successes and failures, associated with a bulk conversation status update. **Type:** object **Properties:** - **totalConversationsCount** (integer) - The total number of conversations being updated. - **updateFailureCount** (integer) - The number of conversations in which the specified update failed. - **updateSuccessCount** (integer) - The number of conversations in which the specified update succeeded. ### ConversationsResponse **Description:** This type provides the updated information for a conversation that has been modified. **Type:** object **Properties:** - **conversationId** (string) - The unique identifier of the conversation. - **updateStatus** (string) - The update status of the conversation, such as `SUCCESS` or `FAILURE`. ### GetAllMyConversationsResponse **Description:** This type defines the response payload of the **getConversations** method. **Type:** object **Properties:** - **conversations** (array) - This array returns the conversations that match the filter criteria. Each conversation is returned with information such as its ID, status, title, type, and creation date, as well as the latest message in the conversation. - **href** (string) - The URI to the current page of results. - **limit** (integer) - The value of the **limit** parameter submitted in the request. - **next** (string) - The URI for the next page of results. This value is returned if there is an additional page of results in the result set. - **offset** (integer) - The value of the **offset** parameter submitted in the request. - **prev** (string) - The URI for the previous page of results. This value is only returned if there is a previous page of results in the result set. - **total** (integer) - The total number of entries returned in the result set. ### GetMessagesByConversationIdResponse **Description:** This type defines the response payload of the **getConversation** method. **Type:** object **Properties:** - **conversationStatus** (string) - The current status of the conversation, such as `ACTIVE` or `ARCHIVE`. - **conversationTitle** (string) - The title of the conversation. - **conversationType** (string) - The type of the conversation, such as `FROM_EBAY` or `FROM_MEMBERS`. - **href** (string) - The URI to the current page of results. - **limit** (integer) - The value of the **limit** parameter submitted in the request. - **messages** (array) - This array returns a list of messages from the specified conversation. - **next** (string) - The URI for the next page of results. This value is only returned if there is an additional page of results in the result set. - **offset** (integer) - The value of the **offset** parameter submitted in the request. - **prev** (string) - The URI for the previous page of results. This value is only returned if there is a previous page of results in the result set. - **total** (integer) - The total number of entries returned in the result set. ### MessageDetail **Description:** This type defines the message details for a conversation. **Type:** object **Properties:** - **createdDate** (string) - The date, in ISO 8601 format, the message was received. - **messageBody** (string) - The message text. - **messageId** (string) - The unique identifier of the message. - **messageMedia** (array) - This array returns a list, if applicable, of media attached to the message. - **readStatus** (boolean) - This boolean indicates if the message has been viewed by the recipient. If this boolean is returned as `true`, the message has been read. If this boolean is returned as `false`, the message has not been read. - **recipientUsername** (string) - The eBay username of the message recipient. **Note:** Effective September 26, 2025, select developers will no longer receive username data for U.S. users through this field. Instead, an immutable user ID will be returned in its place. For more information, please refer to [Data Handling Compliance](/api-docs/static/data-handling-update.html). - **senderUsername** (string) - The eBay username of the message sender. **Note:** Effective September 26, 2025, select developers will no longer receive username data for U.S. users through this field. Instead, an immutable user ID will be returned in its place. For more information, please refer to [Data Handling Compliance](/api-docs/static/data-handling-update.html). - **subject** (string) - The subject line of the message. ### MessageMedia **Description:** This type specifies the format of media that was included when sending a message. **Type:** object **Properties:** - **mediaName** (string) - The name of the media attached to the message. - **mediaType** (string) - The type of media attached to the message. **Valid values:** * `IMAGE` * `PDF` * `DOC` * `TXT` - **mediaUrl** (string) - The URL of the self-hosted media attached to the message. URLs must use the "HTTPS" protocol. ### Reference **Description:** This type specifies the reference type and associated reference ID associated with a message. **Type:** object **Properties:** - **referenceId** (string) - This value indicates the reference ID associated with the corresponding **referenceType** value. For example, in the case of a `LISTING` reference type, this value will be the item ID value of the listing. - **referenceType** (string) - This value indicates the reference type to associate with the conversation. The reference type is used to specify what the conversation is in reference to. For example, a value of `LISTING` specifies that the conversation is associated with a specific listing. The item ID associated with this listing will then be returned in the **referenceId** field. Currently, only the `LISTING` reference type is supported. ### SendMessageRequest **Description:** This type defines the request payload of the **sendMessage** method. **Type:** object **Properties:** - **conversationId** (string) - This field specifies the unique identifier of the conversation in which to send the message. Use the [getConversations](/develop/api/sell/message_api#sell-message_api-conversation-getconversations) method to retrieve conversation ID values. This field is required if sending a message in an existing conversation. - **emailCopyToSender** (boolean) - This boolean indicates whether a copy of the message should be emailed to the sender. If this boolean is input as `true`, a copy of the message will be emailed to the sender. - **messageMedia** (array) - This array lists the individual forms of media, if any, to be attached to the message. Up to five individual forms of media may be sent per message. If more than five are specified in this array, an error will occur and the call will fail. - **messageText** (string) - The text of the message. **Maximum length:** 2000 characters - **otherPartyUsername** (string) - This field specifies the eBay username of the entity to whom to send the message. This field is required if starting a new conversation with another eBay user. **Note:** Effective September 26, 2025, select developers will no longer receive username data for U.S. users through this field. Instead, an immutable user ID will be returned in its place. For more information, please refer to [Data Handling Compliance](/api-docs/static/data-handling-update.html). - **reference** (Reference) - This container should be used if the new or existing conversation is related to a specific eBay listing. For example, a **referenceType** of `LISTING` and an associated **referenceId** will specify the item ID value of the listing associated with the message. ### SendMessageResponse **Description:** This type defines the response payload of the **sendMessage** method. **Type:** object **Properties:** - **createdDate** (string) - The date the message was sent in ISO 8601 format. - **messageBody** (string) - The message text. - **messageId** (string) - The unique identifier of the message. - **messageMedia** (array) - This array will be returned if the user attached one or more images or documents to the message. - **readStatus** (boolean) - The read status of the message. If returned as `true`, the message has been read. If returned as `false`, the message has not been read. - **recipientUserName** (string) - The eBay username of the recipient. **Note:** Effective September 26, 2025, select developers will no longer receive username data for U.S. users through this field. Instead, an immutable user ID will be returned in its place. For more information, please refer to [Data Handling Compliance](/api-docs/static/data-handling-update.html). - **senderUserName** (string) - The eBay username of the sender. **Note:** Effective September 26, 2025, select developers will no longer receive username data for U.S. users through this field. Instead, an immutable user ID will be returned in its place. For more information, please refer to [Data Handling Compliance](/api-docs/static/data-handling-update.html). - **subject** (string) - The subject line of the message. ### UpdateConversationRequest **Description:** This type defines the request payload of the **updateConversation** method. **Type:** object **Properties:** - **conversationId** (string) - This field specifies the unique identifier of the conversation that is to be updated. Use the [getConversations](/develop/api/sell/message_api#sell-message_api-conversation-getconversations) method to retrieve conversation ID values. - **conversationStatus** (string) - This field specifies the status for which to update the specified conversation. **Valid values:** * `ACTIVE` * `ARCHIVE` * `DELETE` **Note:** This field should not be used in conjunction with the **read** field. If both fields are input in the request, only the **read** status will be updated for the specified conversation and the **conversationStatus** field will be ignored. - **conversationType** (string) - This field specifies the existing type of the conversation being updated. **Important!** This value **cannot** be updated using this method but is required as part of the request payload. **Valid values:** * `FROM_MEMBERS` * `FROM_EBAY` - **read** (boolean) - This boolean specifies the read status for which to update the conversation. If set to `true`, the conversation will update to 'read', and if set to `false`, the conversation will update to 'unread'. **Note:** This field should not be used in conjunction with the **conversationStatus** field. If both fields are input in the request, only the **read** status will be updated for the specified conversation and the **conversationStatus** field will be ignored. ## Rate Limits See [API Call Limits](https://developer.ebay.com/develop/get-started/api-call-limits) on the eBay Developer Program. ## Resources ### Documentation - [eBay Developer Program](https://developer.ebay.com/) - [API Documentation](https://developer.ebay.com/develop/api/) - [SDKs and Widgets](https://developer.ebay.com/develop/sdks-and-widgets) - [Developer Community Forum](https://community.ebay.com/t5/Developer-Groups/ct-p/developergroup) ### Tools - [API Explorer](https://developer.ebay.com/my/api_test_tool) - [GraphQL Explorer](https://developer.ebay.com/my/graphql_explorer) ### Support - [Developer Support](https://developer.ebay.com/support/) - [API Status](https://developer.ebay.com/support/api-status) - [Release Notes](https://developer.ebay.com/develop/api/release_notes/) --- *Generated on 2026-04-29T11:16:23.476Z*