Batch get messages

Retrieves multiple SMS message records in a single batch request (up to 100 message IDs), returning the individual retrieval outcome (success: true with the projected message, or success: false with an error object) for each requested ID. 

POST /api/v2/messages:batchGet

Table of contents

Endpoint summary

Property Value
HTTP method POST
Endpoint path /api/v2/messages:batchGet
Authentication Authorization: Bearer <api_key> or Authorization: Basic <base64(username:password)>
Content-Type application/json
Success status code 200 OK

Note: Missing message IDs do not cause the entire batch request to fail. Instead, the endpoint returns 200 OK and reports individual outcomes per ID in the results array. By default (view: "basic"), payload content fields (content, hexContent, userDataHeader, dataCoding) are omitted; specify "view": "full" to include message payloads.

Request

Request headers

Header Required Description
Authorization Yes Credentials identifying the user account context (Bearer <api_key> or Basic <credentials>).
Content-Type Yes Must be application/json.

Request body

The request body must be a JSON object with strictly case-sensitive camelCase property names.

Parameters (BatchGetMessagesRequest)

Field Type Required Default Description
messageIds string (UUID)[] Yes — Non-empty array of message identifiers to retrieve (minimum 1, maximum 100 non-empty strings).
view string Optional "basic" Controls which fields are projected on each retrieved message: "basic", "status_only", or "full".

View projections (MessageView)

View Included fields
"basic" (default) Returns core message metadata (messageId, folder, from, to, type, createdAt, scheduledAt, expiresAt) and delivery status (status, statusDescription, updatedAt), omitting payload body fields (content, hexContent, userDataHeader, dataCoding).
"status_only" Returns only messageId and delivery status fields (status, statusDescription, updatedAt). For inbox or deleted messages where delivery status does not apply, only messageId is returned.
"full" Returns the complete message representation, including core metadata, delivery status, and payload fields (content for "SMS:TEXT", or hexContent, userDataHeader, and dataCoding for "SMS:BINARY").

Response

200 OK

Returns a BatchGetMessagesResponse object containing the ordered results array corresponding 1-to-1 with the requested messageIds.

Root object (BatchGetMessagesResponse)

Field Type Description
results object[] (BatchGetResultItem[]) Array of individual retrieval outcomes in the exact order of messageIds.

results[] item object (BatchGetResultItem)

Field Type Presence Description
messageId string (UUID) Always The queried message identifier.
success boolean Always true if the message was found and retrieved; false if not found.
message object (MessageResponse) When success is true The retrieved message record projected according to view. Omitted when success is false.
error object (ApiErrorDetail) When success is false Structured error details explaining why retrieval failed (e.g., 404 Not Found). Omitted when success is true.

message object (MessageResponse)

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

Field Type Views Folders Description
messageId string (UUID) basic, status_only, full All Unique identifier of the message.
folder string basic, full All Message folder ("inbox", "outbox", "postponed", "sent", "notsent", or "deleted").
from string basic, full All Sender phone number (E.164) or alphanumeric sender ID. Omitted if null or empty.
to string basic, full All Destination recipient phone number.
type string basic, full All Message payload type ("text" or "binary").
content string full All Text payload content. Present only when view is "full" and type is "text".
hexContent string full All Hexadecimal-encoded binary payload. Present only when view is "full" and type is "binary".
userDataHeader string full All Hexadecimal-encoded User Data Header (UDH). Present only when view is "full", type is "binary", and UDH was set.
dataCoding integer full All Data coding scheme (DCS). Present only when view is "full" and type is "binary".
status string basic, status_only, full outbox, postponed, sent, notsent Delivery status state ("queued", "rejected", "submitted", "partiallysubmitted", "submitfailed", "delivered", "partiallydelivered", "deliveryfailed", "viewed"). Omitted for "inbox" or "deleted" folders.
statusDescription string basic, status_only, full outbox, postponed, sent, notsent Human-readable explanation corresponding to status. Omitted for "inbox" or "deleted" folders.
updatedAt string (ISO 8601) basic, status_only, full outbox, postponed, sent, notsent Timestamp of the last delivery status transition. Omitted for "inbox" or "deleted" folders.
createdAt string (ISO 8601) basic, full All Timestamp when the message was created or received.
scheduledAt string (ISO 8601) basic, full All Scheduled dispatch timestamp.
expiresAt string (ISO 8601) basic, full All Expiration deadline timestamp.

error object (ApiErrorDetail)

Field Type Description
code integer HTTP status code for the item failure (e.g., 404).
description string Explanation of why the specific message could not be retrieved.
action string Recommended action to resolve the item error.
timestamp string (ISO 8601) Timestamp when the error was evaluated.

Error responses

When authentication fails, the JSON body is malformed, or request-level validation fails (such as an empty messageIds array, more than 100 IDs, a blank ID element, or an invalid view), the API returns a top-level ApiErrorResponse object.

Common error status codes:

Status code Condition Description
401 Unauthorized Missing or invalid credentials Authentication credentials were not provided or could not be resolved to an active user.
422 Unprocessable Entity Request validation error messageIds is missing, empty, exceeds 100 items, contains a null/whitespace ID, or view is not one of "basic", "status_only", "full".

Error schema (ApiErrorResponse):

Field Type Description
error.code integer HTTP status code (e.g., 401, 422).
error.description string Explanation of the specific error condition.
error.action string Recommended action to resolve the error.
error.timestamp string (ISO 8601) Timestamp when the error occurred.

Examples

1. Batch get messages with partial failures (view: "basic")

Queries four message IDs using the default basic view: two outbound messages in sent, one non-existent message ID (returning an inline 404 item error), and one inbound message in inbox.

Request headers: 

POST /api/v2/messages:batchGet HTTP/1.1
Host: localhost:9509
Authorization: Bearer <api_key>
Content-Type: application/json

Request body: 

{
  "messageIds": [
    "26385eed-6a6c-4deb-b549-dc055211a71d",
    "8f3b2a1c-9d4e-4f5a-b6c7-1a2b3c4d5e6f",
    "9e4c3b2d-0e5f-4a6b-c7d8-2b3c4d5e6f7a",
    "b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e"
  ]
}

Response (200 OK): 

{
  "results": [
    {
      "messageId": "26385eed-6a6c-4deb-b549-dc055211a71d",
      "success": true,
      "message": {
        "messageId": "26385eed-6a6c-4deb-b549-dc055211a71d",
        "folder": "sent",
        "from": "+36201002000",
        "to": "+36201002001",
        "type": "text",
        "status": "delivered",
        "statusDescription": "Delivered",
        "createdAt": "2026-10-21T10:20:00+02:00",
        "scheduledAt": "2026-10-21T10:20:00+02:00",
        "expiresAt": "2026-10-28T10:20:00+02:00",
        "updatedAt": "2026-10-21T10:21:00+02:00"
      }
    },
    {
      "messageId": "8f3b2a1c-9d4e-4f5a-b6c7-1a2b3c4d5e6f",
      "success": true,
      "message": {
        "messageId": "8f3b2a1c-9d4e-4f5a-b6c7-1a2b3c4d5e6f",
        "folder": "sent",
        "from": "+36201003000",
        "to": "+36201003001",
        "type": "text",
        "status": "deliveryfailed",
        "statusDescription": "Delivery failed",
        "createdAt": "2026-10-21T10:20:00+02:00",
        "scheduledAt": "2026-10-21T10:20:00+02:00",
        "expiresAt": "2026-10-28T10:20:00+02:00",
        "updatedAt": "2026-10-21T10:21:00+02:00"
      }
    },
    {
      "messageId": "9e4c3b2d-0e5f-4a6b-c7d8-2b3c4d5e6f7a",
      "success": false,
      "error": {
        "code": 404,
        "description": "Message with ID '9e4c3b2d-0e5f-4a6b-c7d8-2b3c4d5e6f7a' was not found.",
        "action": "Verify that message ID '9e4c3b2d-0e5f-4a6b-c7d8-2b3c4d5e6f7a' exists and was dispatched by the current user.",
        "timestamp": "2026-10-21T10:21:00+02:00"
      }
    },
    {
      "messageId": "b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e",
      "success": true,
      "message": {
        "messageId": "b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e",
        "folder": "inbox",
        "from": "+36201004000",
        "to": "+36201004001",
        "type": "text",
        "createdAt": "2026-10-21T10:21:00+02:00",
        "scheduledAt": "2026-10-21T10:21:00+02:00",
        "expiresAt": "2026-10-28T10:21:00+02:00"
      }
    }
  ]
}

2. Batch get messages with full payload (view: "full")

Retrieves complete message representations including payload content.

Request headers: 

POST /api/v2/messages:batchGet HTTP/1.1
Host: localhost:9509
Authorization: Bearer <api_key>
Content-Type: application/json

Request body: 

{
  "messageIds": [
    "26385eed-6a6c-4deb-b549-dc055211a71d",
    "b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e"
  ],
  "view": "full"
}

Response (200 OK): 

{
  "results": [
    {
      "messageId": "26385eed-6a6c-4deb-b549-dc055211a71d",
      "success": true,
      "message": {
        "messageId": "26385eed-6a6c-4deb-b549-dc055211a71d",
        "folder": "sent",
        "from": "+36201002000",
        "to": "+36201002001",
        "type": "text",
        "content": "Message 1 goes to 1 number",
        "status": "delivered",
        "statusDescription": "Delivered",
        "createdAt": "2026-10-21T10:20:00+02:00",
        "scheduledAt": "2026-10-21T10:20:00+02:00",
        "expiresAt": "2026-10-28T10:20:00+02:00",
        "updatedAt": "2026-10-21T10:21:00+02:00"
      }
    },
    {
      "messageId": "b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e",
      "success": true,
      "message": {
        "messageId": "b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e",
        "folder": "inbox",
        "from": "+36201004000",
        "to": "+36201004001",
        "type": "text",
        "content": "Incoming reply message",
        "createdAt": "2026-10-21T10:21:00+02:00",
        "scheduledAt": "2026-10-21T10:21:00+02:00",
        "expiresAt": "2026-10-28T10:21:00+02:00"
      }
    }
  ]
}

3. Batch get delivery statuses only (view: "status_only")

Polls only the delivery status fields (messageId, status, statusDescription, updatedAt) for a list of outbound message IDs.

Request headers: 

POST /api/v2/messages:batchGet HTTP/1.1
Host: localhost:9509
Authorization: Bearer <api_key>
Content-Type: application/json

Request body: 

{
  "messageIds": [
    "26385eed-6a6c-4deb-b549-dc055211a71d",
    "8f3b2a1c-9d4e-4f5a-b6c7-1a2b3c4d5e6f"
  ],
  "view": "status_only"
}

Response (200 OK): 

{
  "results": [
    {
      "messageId": "26385eed-6a6c-4deb-b549-dc055211a71d",
      "success": true,
      "message": {
        "messageId": "26385eed-6a6c-4deb-b549-dc055211a71d",
        "status": "delivered",
        "statusDescription": "Delivered",
        "updatedAt": "2026-10-21T10:21:00+02:00"
      }
    },
    {
      "messageId": "8f3b2a1c-9d4e-4f5a-b6c7-1a2b3c4d5e6f",
      "success": true,
      "message": {
        "messageId": "8f3b2a1c-9d4e-4f5a-b6c7-1a2b3c4d5e6f",
        "status": "deliveryfailed",
        "statusDescription": "Delivery failed",
        "updatedAt": "2026-10-21T10:21:00+02:00"
      }
    }
  ]
}

4. Error: Empty messageIds array (422 Unprocessable Entity)

Returned when messageIds is missing or contains no items.

Response (422 Unprocessable Entity): 

{
  "error": {
    "code": 422,
    "description": "The 'messageIds' array is required and must contain at least one item.",
    "action": "Provide a non-empty array of message IDs (up to 100).",
    "timestamp": "2026-10-21T10:21:00+02:00"
  }
}

5. Error: Invalid view field (422 Unprocessable Entity)

Returned when the view property in the request body specifies an unrecognized projection name.

Response (422 Unprocessable Entity): 

{
  "error": {
    "code": 422,
    "description": "Invalid view 'detailed'.",
    "action": "Field 'view' must be one of: 'basic', 'status_only', 'full'.",
    "timestamp": "2026-10-21T10:21:00+02:00"
  }
}

More information