---
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
api_name: message_api
api_type: REST
api_group: sell/message_api
source_url:
  html: https://developer.ebay.com/develop/api/sell/message_api
  md: https://developer.ebay.com/develop/api/sell/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 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**.

### 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

### 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`.

### 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**.

### 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**.

## 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.

## 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-07-08T04:31:13.566Z*