Get SMS logs

Returns the agent's SMS logs, newest first, with pagination and filtering by delivery attributes (status, recipient, sender name) and request attributes (client reference, template, request id, date range).

Endpoint

get /sms/logs

Copy full URL

Request URL

https://cpaas.zoho.com/v1.1/sms/logs 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.

- Query Parameters

offsetintegerOptional

Zero-based offset for pagination.

Default Value :0Copied!

limitintegerOptional

Maximum number of log entries to return.

Default Value :10Copied!

statusstringOptional

Filter by message status. Common values: delivered, sent, not-sent, undelivered, failed, processed, process_failed, spam. Detailed telecom/DLT failure codes (e.g. dnd-number, inv-number, tl-nt-found) are also accepted.

recipientstring(length <= 30)Optional

Filter by recipient mobile number (with country code).

Maximum Length :30Copied!

sender_namestring(length <= 30)Optional

Filter by sender name.

Maximum Length :30Copied!

client_referencestring(length <= 100)Optional

Filter by the client reference supplied at send time.

Maximum Length :100Copied!

template_keystring(length <= 50)Optional

Filter by SMS template key.

Maximum Length :50Copied!

request_idstring(length <= 200)Optional

Filter by the request id returned by the send API.

Maximum Length :200Copied!

date_fromdate-timeOptional

Start of the date range - an ISO 8601 date-time with UTC offset.

date_todate-timeOptional

End of the date range - an ISO 8601 date-time with UTC offset.

Sample Request

Curl

Java

Python

Deluge

Copied!

curl --request GET \
  --url 'https://cpaas.zoho.com/v1.1/sms/logs?offset=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE&status=delivered&recipient=SOME_STRING_VALUE&sender_name=SOME_STRING_VALUE&client_reference=SOME_STRING_VALUE&template_key=SOME_STRING_VALUE&request_id=SOME_STRING_VALUE&date_from=2026-09-22T00:00:00+05:30&date_to=2026-09-22T23:59:59+05:30' \
  --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?offset=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE&status=delivered&recipient=SOME_STRING_VALUE&sender_name=SOME_STRING_VALUE&client_reference=SOME_STRING_VALUE&template_key=SOME_STRING_VALUE&request_id=SOME_STRING_VALUE&date_from=2026-09-22T00:00:00+05:30&date_to=2026-09-22T23:59:59+05:30"))
        .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?offset=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE&status=delivered&recipient=SOME_STRING_VALUE&sender_name=SOME_STRING_VALUE&client_reference=SOME_STRING_VALUE&template_key=SOME_STRING_VALUE&request_id=SOME_STRING_VALUE&date_from=2026-09-22T00:00:00+05:30&date_to=2026-09-22T23:59:59+05:30", headers=headers)

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

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


    parameters = "offset=value" + "&" + "limit=value" + "&" + "status=value" + "&" + "recipient=value" + "&" + "sender_name=value" + "&" + "client_reference=value" + "&" + "template_key=value" + "&" + "request_id=value" + "&" + "date_from=value" + "&" + "date_to=value";

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

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

    info response;

Response Parameters

- HTTP code 200

Response Body - application/json

JSON Object

Response containing a page of SMS logs.

Show Sub-Attributes

metadataJSON Object

Show Sub-Attributes

offsetinteger

countinteger

Number of entries in this page.

dataJSON Array

Show Sub-Attributes

object

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.

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.

Sample Response: HTTP 200

Copied!

  {
    "metadata": {
      "offset": 0,
      "count": 1
    },
    "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",
        "sender_key": "2d6f4a1b9c35",
        "sender_name": "EXAMPL",
        "agent_id": "11b40318ea8775",
        "to": "919876543210",
        "status": "delivered",
        "process_state": "processed",
        "chunks": "1",
        "is_batch_request": false,
        "request_time": "2026-09-22T16:42:29+05:30",
        "time_taken": 1822
      }
    ],
    "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