Retrieve a message

Retrieves metadata, delivery status, and (optionally) payload content for a single SMS message identified by {messageId}. This unified endpoint handles both inbound (inbox) and outbound (outbox, postponed, sent, notsent, deleted) messages. 

GET /api/v2/messages/{messageId}

Table of contents

Endpoint summary

Property Value
HTTP method GET
Endpoint path /api/v2/messages/{messageId}
Authentication Authorization: Bearer <api_key> or Authorization: Basic <base64(username:password)>
Success status code 200 OK

Note: By default (view=basic), payload content fields (content, hexContent, userDataHeader, dataCoding) are omitted to minimize response size. Pass ?view=full to include the full message payload, or ?view=status_only to retrieve only delivery status fields.

Request

Request headers

Header Required Description
Authorization Yes Credentials identifying the user account context (Bearer <api_key> or Basic <credentials>).

Path parameters

Parameter Type Required Description
messageId string (UUID) Yes Unique identifier of the message to retrieve.

Query parameters

Parameter Type Required Default Description
view string Optional "basic" Controls which fields are projected in the response: "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 "text", or hexContent, userDataHeader, and dataCoding for "binary").

Response

200 OK

Returns a MessageResponse object projected according to the requested view. 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 Current 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=full and type is "text".
hexContent string full All Hexadecimal-encoded binary payload. Present only when view=full and type is "binary".
userDataHeader string full All Hexadecimal-encoded User Data Header (UDH). Present only when view=full, type is "binary", and UDH was set.
dataCoding integer full All Data coding scheme (DCS). Present only when view=full and type is "binary".
status string basic, status_only, full outbox, postponed, sent, notsent Delivery status state. Omitted for messages in "inbox" or "deleted" folders.
statusDescription string basic, status_only, full outbox, postponed, sent, notsent Human-readable explanation corresponding to status (e.g., "Accepted for delivery", "Delivered"). 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.

Message folders

Folder Description
inbox Messages received from external mobile subscribers by the gateway.
outbox Messages submitted by API clients and queued for immediate outbound dispatch.
postponed Messages scheduled for deferred outbound dispatch (scheduledAt > createdAt).
sent Outbound messages submitted to the network or delivered to recipients.
notsent Outbound messages that were rejected or failed submission to the provider.
deleted Outbound messages cancelled or deleted.

Message delivery statuses

Status Folder scope Description
queued outbox, postponed SMS accepted by gateway and queued awaiting dispatch.
rejected notsent Message rejected prior to submission due to validation or policy.
submitted sent Message successfully submitted to the telecom provider/SMSC.
partiallysubmitted sent Multi-part message partially submitted to provider network.
submitfailed notsent Transmission attempt to provider/SMSC failed.
delivered sent Message successfully confirmed delivered to recipient handset.
partiallydelivered sent Multi-part message partially confirmed delivered.
deliveryfailed sent Message delivery failed (e.g., unreachable, expired, or invalid subscriber).
viewed sent Recipient has read or viewed the message payload (where supported).

Error responses

When the requested message does not exist, authentication fails, or the view query parameter is invalid, the API returns a structured 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.
404 Not Found Message not found No message matching {messageId} exists across any folder for the authenticated user account.
422 Unprocessable Entity Invalid view parameter The view query parameter is not one of "basic", "status_only", or "full".

Error schema (ApiErrorResponse):

Field Type Description
error.code integer HTTP status code (e.g., 401, 404, 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. Retrieve an outbox message (view=full)

Retrieves the full representation (including content) of an outbound message currently queued in the outbox folder.

Request: 

GET /api/v2/messages/26385eed-6a6c-4deb-b549-dc055211a71d?view=full HTTP/1.1
Host: localhost:9509
Authorization: Bearer <api_key>

Response (200 OK): 

{
  "messageId": "26385eed-6a6c-4deb-b549-dc055211a71d",
  "folder": "outbox",
  "from": "+36201002000",
  "to": "+36201002001",
  "type": "text",
  "content": "Message 1 goes to 1 number",
  "status": "queued",
  "statusDescription": "Accepted for delivery",
  "updatedAt": "2026-10-21T10:20: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"
}

2. Retrieve a delivered sent message (view=full)

Retrieves the full representation of an outbound message that has been delivered to the recipient (folder: "sent", status: "delivered").

Request: 

GET /api/v2/messages/26385eed-6a6c-4deb-b549-dc055211a71d?view=full HTTP/1.1
Host: localhost:9509
Authorization: Bearer <api_key>

Response (200 OK): 

{
  "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",
  "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"
}

3. Retrieve an inbound inbox message (view=full)

Retrieves an incoming SMS message from the inbox folder. Because delivery status tracking applies only to outbound messages, status, statusDescription, and updatedAt are omitted.

Request: 

GET /api/v2/messages/26385eed-6a6c-4deb-b549-dc055211a71d?view=full HTTP/1.1
Host: localhost:9509
Authorization: Bearer <api_key>

Response (200 OK): 

{
  "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"
}

4. Retrieve delivery status only (view=status_only)

Queries only the delivery status attributes of an outbound message using view=status_only.

Request: 

GET /api/v2/messages/26385eed-6a6c-4deb-b549-dc055211a71d?view=status_only HTTP/1.1
Host: localhost:9509
Authorization: Bearer <api_key>

Response (200 OK): 

{
  "messageId": "26385eed-6a6c-4deb-b549-dc055211a71d",
  "status": "delivered",
  "statusDescription": "Delivered",
  "updatedAt": "2026-10-21T10:21:00+02:00"
}

5. Retrieve a message with default basic view (view=basic)

When view is omitted (or set to basic), core metadata and delivery status are returned without payload body fields.

Request: 

GET /api/v2/messages/26385eed-6a6c-4deb-b549-dc055211a71d HTTP/1.1
Host: localhost:9509
Authorization: Bearer <api_key>

Response (200 OK): 

{
  "messageId": "26385eed-6a6c-4deb-b549-dc055211a71d",
  "folder": "sent",
  "from": "+36201002000",
  "to": "+36201002001",
  "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"
}

6. Error: Message not found (404 Not Found)

Returned when the requested message ID does not exist in any folder for the authenticated user.

Response (404 Not Found): 

{
  "error": {
    "code": 404,
    "description": "Message with ID '26385eed-0000-0000-0000-000000000000' was not found.",
    "action": "Verify that message ID '26385eed-0000-0000-0000-000000000000' exists and was dispatched by the current user.",
    "timestamp": "2026-10-21T10:21:00+02:00"
  }
}

7. Error: Invalid view query parameter (422 Unprocessable Entity)

Returned when the view query parameter specifies an unrecognized projection name.

Response (422 Unprocessable Entity): 

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

More information