Get SMS message details

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

Endpoint

get /sms/logs/{message_id}

Copy full URL

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}.
Follow the steps here to generate an API key.

- Path Parameters

message_iduuidMandatory

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

Example

7fff7400-b676-11f1-b0ad-b6d94062a427

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'

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.io.IOException;
import java.net.http.HttpTimeoutException;

public class Main {
  public static void main(String[] args) {

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://cpaas.zoho.com/v1.1/sms/logs/7fff7400-b676-11f1-b0ad-b6d94062a427"))
        .header("Authorization", "REPLACE_KEY_VALUE")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .build();
    HttpResponse response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
  
  }
}

import http.client

conn = http.client.HTTPSConnection("cpaas.zoho.com")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("GET", "/v1.1/sms/logs/7fff7400-b676-11f1-b0ad-b6d94062a427", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))


    headersMap = Map();
    headersMap.put("Authorization", "REPLACE_KEY_VALUE");
    headersMap.put("Accept", "application/json");

    response = invokeUrl
    [
        url: "https://cpaas.zoho.com/v1.1/sms/logs/{message_id}"
        type: GET
        headers: headersMap
        connection: connection_name
    ]

    info response;

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).

Example

delivered

process_statestring

Processing state of the request.

Example

processed

remote_ipstring

IP address the send request was made from.

Example

10.61.232.23

chunksstring

Number of SMS parts the message was split into.

Example

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.

Example

otp-template

contentJSON Object

The message content that was sent.

Show Sub-Attributes

body_textstring

Rendered message text, with merge tags resolved.

Example

Your one-time password is 482913. It is valid for 10 minutes.

eventsarray[object]

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.

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).

Example

VOI_502

messagestring

Failure message.

Example

Call initiation failed

error_msgstring

The same failure information serialized as a JSON string.

Example

{"code":"SMS_108","message":"sms.api.sms.server.error.throw"}

statusstring

Example

success

- 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

Example

TM_3301

messagestring

Example

Bad Syntax

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).

Example

SERR_110

messagestring

Example

Parameter less than min occurrance

targetstring

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

Example

sender_key

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

Show Sub-Attributes

errorJSON Object

Show Sub-Attributes

codestring

Example

TM_3301

messagestring

Example

Bad Syntax

detailsJSON Array

Show Sub-Attributes

object

A single validation or denial detail inside the error envelope.

codestring

Example

SERR_110

messagestring

Example

Parameter less than min occurrance

targetstring

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

Example

sender_key

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