BSV blockchainBSV blockchain

Retrieve messages from a named message box

POST/listMessages

Returns one deterministic, bounded page of stored messages belonging to the authenticated identity in the specified message box. Returns an empty array if the box does not exist. Message bodies are always returned as strings (JSON objects are stringified).

Body application/json

messageBoxstringrequired

Name of the message box to retrieve messages from.

limitinteger
offsetinteger
skipinteger

Compatibility alias for offset; both must match if supplied together.

Response

Messages retrieved successfully (array may be empty).

status"success"
messagesobject[]
Show messages properties
messageIdstring
bodystring

Stringified message body (JSON objects are JSON.stringify-ed before storage).

senderstring

Compressed secp256k1 public key encoded as a 66-character hex string.

createdAtstring<date-time>
updatedAtstring<date-time>
limitinteger
offsetinteger
nextOffsetinteger

Offset for the next page; unchanged when the result is empty.

hasMoreboolean

Invalid or missing message box name. Codes: ERR_MESSAGEBOX_REQUIRED, ERR_INVALID_MESSAGEBOX

status"error"
codestring

Machine-readable error code (see specs/errors.md).

descriptionstring

Human-readable explanation.

Authentication required.

status"error"
codestring

Machine-readable error code (see specs/errors.md).

descriptionstring

Human-readable explanation.

Internal server error (ERR_INTERNAL_ERROR).

status"error"
codestring

Machine-readable error code (see specs/errors.md).

descriptionstring

Human-readable explanation.

Request
curl -X POST "https://{host}/listMessages" \
  -H "Content-Type: application/json" \
  -H "x-bsv-auth-identity-key: <x-bsv-auth-identity-key>" \
  -d '{
  "messageBox": "string",
  "limit": 1000,
  "offset": 0,
  "skip": 0
}'
Response
{
  "status": "success",
  "messages": [
    {
      "messageId": "string",
      "body": "string",
      "sender": "string",
      "createdAt": "1970-01-01T00:00:00.000Z",
      "updatedAt": "1970-01-01T00:00:00.000Z"
    }
  ],
  "limit": 0,
  "offset": 0,
  "nextOffset": 0,
  "hasMore": true
}