List messages

Returns a paginated list of SMS messages for the authenticated user account, with optional filtering by message folder and configurable field projection views.

GET /api/v2/messages

Table of contents

Endpoint summary

Request

Request headers

Query parameters (ListMessagesQueryParams)

View projections (MessageView)

Message folders

Response

200 OK

Returns a ListMessagesResponse object containing the array of matching message records and pagination metadata.

Root object (ListMessagesResponse)

messages[] item object (MessageResponse)

Properties with null values are omitted from the serialized JSON output.

pagination object (PaginationMetadata)

Error responses

When authentication fails or any query parameter (folder, limit, offset, view) is invalid, the API returns a structured ApiErrorResponse object.

Common error status codes:

Error schema (ApiErrorResponse):

Examples

1. List messages across all folders (view=full)

Retrieves up to 100 messages across all folders with full payload details included.

Request:

GET /api/v2/messages?limit=100&offset=0&view=full HTTP/1.1
Host: localhost:9509
Authorization: Bearer <api_key>

Response (200 OK):

{
  "messages": [
    {
      "messageId": "26385eed-6a6c-4deb-b549-dc055211a71d",
      "folder": "inbox",
      "from": "+36201002000",
      "to": "+36201002001",
      "type": "text",
      "content": "Message 1 goes to 1 number",
      "createdAt": "2026-10-21T10:21:00+02:00",
      "scheduledAt": "2026-10-21T10:21:00+02:00",
      "expiresAt": "2026-10-28T10:21:00+02:00"
    },
    {
      "messageId": "8f3b2a1c-9d4e-4f5a-b6c7-1a2b3c4d5e6f",
      "folder": "sent",
      "from": "+36201003000",
      "to": "+36201003001",
      "type": "text",
      "content": "Message 2 goes to 2 number",
      "status": "delivered",
      "statusDescription": "Delivered",
      "updatedAt": "2026-10-21T10:21:00+02:00",
      "createdAt": "2026-10-21T10:20:00+02:00",
      "scheduledAt": "2026-10-21T10:20:00+02:00",
      "expiresAt": "2026-10-28T10:20:00+02:00"
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 2
  }
}

2. List incoming messages in inbox (folder=inbox&view=full)

Retrieves only incoming SMS messages from the inbox folder with full message content.

Request:

GET /api/v2/messages?folder=inbox&limit=100&offset=0&view=full HTTP/1.1
Host: localhost:9509
Authorization: Bearer <api_key>

Response (200 OK):

{
  "messages": [
    {
      "messageId": "26385eed-6a6c-4deb-b549-dc055211a71d",
      "folder": "inbox",
      "from": "+36201002000",
      "to": "+36201002001",
      "type": "text",
      "content": "Message 1 goes to 1 number",
      "createdAt": "2026-10-21T10:21:00+02:00",
      "scheduledAt": "2026-10-21T10:21:00+02:00",
      "expiresAt": "2026-10-28T10:21:00+02:00"
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 1
  }
}

3. List outgoing queued messages in outbox (folder=outbox&view=full)

Retrieves outbound messages currently queued in the outbox folder.

Request:

GET /api/v2/messages?folder=outbox&limit=100&offset=0&view=full HTTP/1.1
Host: localhost:9509
Authorization: Bearer <api_key>

Response (200 OK):

{
  "messages": [
    {
      "messageId": "37492ffd-7b7d-4efc-c65a-ed166322b82e",
      "folder": "outbox",
      "from": "+36201002000",
      "to": "+36201002001",
      "type": "text",
      "content": "Queued outbound message",
      "status": "queued",
      "statusDescription": "Accepted for delivery",
      "updatedAt": "2026-10-21T10:21:00+02:00",
      "createdAt": "2026-10-21T10:21:00+02:00",
      "scheduledAt": "2026-10-21T10:21:00+02:00",
      "expiresAt": "2026-10-28T10:21:00+02:00"
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 1
  }
}

4. List sent messages with default basic view (folder=sent)

Retrieves messages from the sent folder using the default basic view (metadata and delivery status, without payload content).

Request:

GET /api/v2/messages?folder=sent&limit=100&offset=0 HTTP/1.1
Host: localhost:9509
Authorization: Bearer <api_key>

Response (200 OK):

{
  "messages": [
    {
      "messageId": "8f3b2a1c-9d4e-4f5a-b6c7-1a2b3c4d5e6f",
      "folder": "sent",
      "from": "+36201003000",
      "to": "+36201003001",
      "type": "text",
      "status": "delivered",
      "statusDescription": "Delivered",
      "updatedAt": "2026-10-21T10:21:00+02:00",
      "createdAt": "2026-10-21T10:20:00+02:00",
      "scheduledAt": "2026-10-21T10:20:00+02:00",
      "expiresAt": "2026-10-28T10:20:00+02:00"
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 1
  }
}

5. List delivery statuses only (folder=sent&view=status_only)

Retrieves only messageId and delivery status fields for messages in the sent folder.

Request:

GET /api/v2/messages?folder=sent&limit=100&offset=0&view=status_only HTTP/1.1
Host: localhost:9509
Authorization: Bearer <api_key>

Response (200 OK):

{
  "messages": [
    {
      "messageId": "8f3b2a1c-9d4e-4f5a-b6c7-1a2b3c4d5e6f",
      "status": "delivered",
      "statusDescription": "Delivered",
      "updatedAt": "2026-10-21T10:21:00+02:00"
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 1
  }
}

6. Error: Invalid limit parameter (422 Unprocessable Entity)

Returned when the limit query parameter is not an integer between 1 and 1000.

Response (422 Unprocessable Entity):

{
  "error": {
    "code": 422,
    "description": "Parameter 'limit' value '-1' is invalid.",
    "action": "Parameter 'limit' must be an integer between 1 and 1000.",
    "timestamp": "2026-10-21T10:21:00+02:00"
  }
}

7. Error: Invalid folder filter (422 Unprocessable Entity)

Returned when the folder query parameter specifies an unrecognized folder name.

Response (422 Unprocessable Entity):

{
  "error": {
    "code": 422,
    "description": "Invalid folder filter 'archive'.",
    "action": "Parameter 'folder' must be one of: 'inbox', 'outbox', 'postponed', 'sent', 'notsent', 'deleted'.",
    "timestamp": "2026-10-21T10:21:00+02:00"
  }
}