Get SMS message details

Open in ChatGPT Open in ChatGPT to ask questions about this page
Open in Claude Open in Claude to ask questions about this page
Copy as MarkdownCopy this page as markdown to use with AI assistants
View as Markdown Open this page as markdown in a new tab

Returns the complete details of a single SMS message, including the rendered message text and the delivery event timeline.

Endpoint

Request URL

https://cpaas.zoho.com/v1.1/sms/logs/{message_id} Copied!

Request Parameters

- Request Headers

ApiKeyAuthAPI Key

API key of an agent. Send the header as Authorization: Zoho-enczapikey {apiKey}. The agent and account are derived from the key.

- Path Parameters

message_iduuidMandatory

Unique identifier of the SMS message, as returned by the send API (data.message_id) or the logs API.

Sample Request

Curl
Java
Python
Deluge
Copied!
curl --request GET \
  --url https://cpaas.zoho.com/v1.1/sms/logs/7fff7400-b676-11f1-b0ad-b6d94062a427 \
  --header 'Authorization: REPLACE_KEY_VALUE'

Response Parameters

- HTTP code 200

Response Body - application/json
JSON Object

Response containing the details of a single SMS message.

Show Sub-Attributes
dataobject

An SMS log entry.

message_iduuid

Unique identifier of the message.

request_idstring

Identifier of the send request.

client_referencestring

Client reference supplied at send time, if any.

template_keyuuid

Key of the SMS template used.

sender_keystring

Key of the sender the message went out as.

sender_namestring

Name of the sender.

agent_idstring

Identifier of the sending agent.

tostring

Recipient mobile number.

statusstring

Message status (e.g. delivered, sent, undelivered, failed, process_failed, or a detailed telecom/DLT failure code).

process_statestring

Processing state of the request.

remote_ipstring

IP address the send request was made from.

chunksstring

Number of SMS parts the message was split into.

is_batch_requestboolean

Whether the message was part of a batch send.

request_timestring

When the send request was received (ISO 8601).

time_takeninteger

Processing time in milliseconds.

template_namestring

Name of the SMS template used.

contentJSON Object

The message content that was sent.

Show Sub-Attributes
body_textstring

Rendered message text, with merge tags resolved.

eventsJSON Array

Chronological delivery events. Present once the message has entered delivery; absent for messages that failed processing (status process_failed). For undelivered messages the failure reason appears in event_data.

Show Sub-Attributes
event_namestring
event_datastring
event_timestring
error_messageJSON Object

Why an accepted message failed asynchronously. Present only on failed messages (voice status PROCESS_FAILED, sms status process_failed).

Show Sub-Attributes
codestring

Failure code (e.g. voice VOI_502, sms SMS_108).

messagestring

Failure message.

error_msgstring

The same failure information serialized as a JSON string.

statusstring

- HTTP code 401

Response Body - application/json
JSON Object

Error response wrapper. The top-level code identifies the error class: TM_3201 mandatory field missing (400), TM_3301 bad syntax (400), TM_4001 access denied (401), TM_3601 request denied (403), TM_3501 unprocessable entity (422).

Show Sub-Attributes
errorJSON Object
Show Sub-Attributes
codestring
messagestring
detailsJSON Array
Show Sub-Attributes
object

A single validation or denial detail inside the error envelope.

codestring

Detail-level error code, e.g. SERR_110 (required parameter missing), SERR_102 (parameter syntax error), GE_102 (mandatory field missing), GE_122 (invalid value), SMS_107 (template not associated with the sending agent), SERR_157 (invalid API token).

messagestring
targetstring

The field the detail refers to, when applicable (e.g. sender_key, to, mobile_no, template_key | template_alias).

target_value

The offending value, when applicable.

request_idstring

Identifier of the failed request, when available.

- HTTP code 403

Response Body - application/json
JSON Object

Error response wrapper. The top-level code identifies the error class: TM_3201 mandatory field missing (400), TM_3301 bad syntax (400), TM_4001 access denied (401), TM_3601 request denied (403), TM_3501 unprocessable entity (422).

Show Sub-Attributes
errorJSON Object
Show Sub-Attributes
codestring
messagestring
detailsJSON Array
Show Sub-Attributes
object

A single validation or denial detail inside the error envelope.

codestring

Detail-level error code, e.g. SERR_110 (required parameter missing), SERR_102 (parameter syntax error), GE_102 (mandatory field missing), GE_122 (invalid value), SMS_107 (template not associated with the sending agent), SERR_157 (invalid API token).

messagestring
targetstring

The field the detail refers to, when applicable (e.g. sender_key, to, mobile_no, template_key | template_alias).

target_value

The offending value, when applicable.

request_idstring

Identifier of the failed request, when available.

Sample Response: HTTP 200

Delivered message with event timeline
Copied!
  {
    "data": {
      "message_id": "7fff7400-b676-11f1-b0ad-b6d94062a427",
      "request_id": "2d6f.14350939.i1.7fff7400-b676-11f1-b0ad-b6d94062a427.1a0c8d26ce9",
      "client_reference": "otp-482913",
      "template_key": "6200ca60-921a-11f1-92c4-2a30dd3b833c",
      "template_name": "otp-template",
      "sender_key": "2d6f4a1b9c35",
      "sender_name": "EXAMPL",
      "agent_id": "11b40318ea8775",
      "to": "919876543210",
      "status": "delivered",
      "process_state": "processed",
      "chunks": "1",
      "is_batch_request": false,
      "content": {
        "body_text": "Your one-time password is 482913. It is valid for 10 minutes."
      },
      "events": [
        {
          "event_name": "processed",
          "event_time": "2026-09-22T16:42:29+05:30"
        },
        {
          "event_name": "delivered",
          "event_data": "SMS successfully delivered.",
          "event_time": "2026-09-22T16:42:35+05:30"
        }
      ],
      "request_time": "2026-09-22T16:42:29+05:30",
      "time_taken": 1822
    },
    "status": "success"
  }
▼ Show full
Message that failed processing - flat error_message {code, message}, no events
Copied!
  {
    "data": {
      "message_id": "ce7b89b0-b5a5-11f1-8210-8688516064a9",
      "request_id": "2d6f.14350939.i1.ce7b89b0-b5a5-11f1-8210-8688516064a9.1a0c8d26ce9",
      "template_key": "6200ca60-921a-11f1-92c4-2a30dd3b833c",
      "template_name": "otp-template",
      "sender_key": "2d6f4a1b9c35",
      "sender_name": "EXAMPL",
      "agent_id": "11b40318ea8775",
      "to": "919876543210",
      "status": "process_failed",
      "process_state": "in-queue",
      "chunks": "2",
      "is_batch_request": false,
      "remote_ip": "10.61.232.23",
      "content": {
        "body_text": "Your one-time password is 482913. It is valid for 10 minutes."
      },
      "error_message": {
        "code": "SMS_108",
        "message": "sms.api.sms.server.error.throw"
      },
      "error_msg": "{\"code\":\"SMS_108\",\"message\":\"sms.api.sms.server.error.throw\"}",
      "request_time": "2026-09-21T15:48:36+05:30",
      "time_taken": 1747
    },
    "status": "success"
  }
▼ Show full

Sample Response: HTTP 401

Copied!
  {
    "error": {
      "code": "TM_4001",
      "details": [
        {
          "code": "SERR_157",
          "message": "Invalid API Token found"
        }
      ],
      "message": "Access Denied"
    }
  }
▼ Show full

Sample Response: HTTP 403

Copied!
  {
    "error": {
      "code": "TM_3601",
      "details": [
        {
          "code": "SERR_120",
          "message": "This URL does not exist"
        }
      ],
      "message": "Request Denied"
    }
  }
▼ Show full

© 2026, Zoho Corporation Pvt. Ltd. All Rights Reserved.