getMessagesList

Retrieves an array of messages lists for the authenticated token's owning user. A "message list" corresponds to a single thread of back-and-forth messages between two users, with an initial message and subsequent messages in reply to each other.

getMessagesList Input

getMessagesList is a secure API method with the following URL and HTTP header requirements:

Submit to URL: https://api.bonanza.com/api_requests/secure_request
Required in HTTP header: X-BONANZLE-API-DEV-NAME set to your dev_id
  X-BONANZLE-API-CERT-NAME set to your cert_id

Note that all secure methods except for fetchToken and getBoothItems require you to submit a user token so that we know what user account you are acting on behalf of.  For details about setting up and submitting user tokens, see our intro to user tokens.

The name for your request should be getMessagesListRequest.

Here are the available input parameters that can be serialized into JSON:

Argument Type Occurrence Meaning
Call-specific Input Fields
filter Container Optional Fetch items from booth that match the specified itemStatus values.
Important: If submitting a request with an item status other than 'for_sale', you must also submit the user token with your request. See the intro to user tokens.
Valid statuses: for_sale, ready_to_post, missing_fields, reserved, sold, and pending_pickup
Default: for_sale
filter.read boolean Optional Filter resulting messages lists to only include messages lists where all messages have been read (true) or messages lists with at least one unread message (false).
filter.saved boolean Optional Filter resulting messages lists to only include messages lists where all messages have been saved (true) or messages lists with at least one unsaved message (false).
pagination.entriesPerPage integer Optional The number of messages lists to return.
Max: 200
Default: 20
pagination.pageNumber integer Optional The page number to fetch.
Default: 1

getMessagesList Output

The name for the output returned from this request is getMessagesListResponse. So, after parsing the serialized response into JSON, you can access the data with something like:

my_json_hash['getMessagesListResponse']

Here are all the possible output parameters:

Argument Type Occurrence Meaning
Standard Output Fields
errorMessage Container Conditionally Description of an error or warning that occurred when Bonanza processed the request. Not returned if the ack value is Success.
errorMessage.error Container Conditionally,
repeatable: [0..*]
errorMessage.error.category ErrorCategory Conditionally Currently unused.
errorMessage.error.message string Conditionally A description of the error
errorMessage.error.type ErrorType Conditionally A unique descriptive name for the error.
timestamp dateTime Always This value represents the date and time when Bonanza processed the request. The time zone of this value is GMT and the format is the ISO 8601 date and time format (YYYY-MM-DDTHH:MM:SS.SSSZ). See the "dateTime" type for information about this time format and converting to and from the GMT time zone.
Call-specific Output Fields
pageNumber integer Always The page number used to fetch the result.
entriesPerPage integer Always The number of messages lists per page used to fetch the result.
totalEntries integer Always The total number of messages lists matching the current filters (if any).
messagesList Container Always, repeatable: [0..*] Contains an array of the messages lists returned.
messagesList[n].messageCount integer Always The total number of messages in the set of messages.
messagesList[n].lastMessageSentAt dateTime Always The date and time at which the last message in the set of messages was sent.
messagesList[n].lastMessageRead boolean Always Whether the last message in the set was read by the receiver.
messagesList[n].lastMessageTo string Always The user name of the user that the last message was sent to.
Fields for first message in set
messagesList[n].id integer Always The id of the message. This can be used as an input to getMessages to get all messages in the set of messages that this message belongs to.
messagesList[n].from string Always The user name of the user that sent the message.
messagesList[n].to string Always The user name of the user that the message was sent to.
messagesList[n].senderPictureURL string Always The URL of the sender's profile picture
messagesList[n].receiverPictureURL string Always The URL of the receiver's profile picture
messagesList[n].sentAt dateTime Always The date and time at which the message was sent.
messagesList[n].subject string Always The subject line of the message.
messagesList[n].body string Always The body of the message. Note that the body may contain HTML.
messagesList[n].read boolean Always

Whether the message has been read by the receiving user.
messagesList[n].saved boolean Always Whether the message has been saved by the receiving user.