Sends an SMS

Sends SMS to a single recipient number. The sender and the template must be pre-configured for the sending agent.

The base message template is a pre-approved SMS template of the sender, addressed by template_key or template_alias. The merge_info is used to resolve the final content by merging the template with values. Params left unresolved are sent literally. sender_key identifies the sender of the SMS. ‘to’ is exactly a single recipient, whose mobile_no must include the country code.

Note:
SMS feature is currently supported for customers hosting their accounts in the IN DC. You can send transactional SMS from your registered sender to customers in India.

Endpoint

Copy full URL

Request URL

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

- Request Body

application/json

JSON Object

Request body for sending a single SMS. Provide exactly one of template_key / template_alias; the template supplies the message text.

Show Sub-Attributes

sender_keystringMandatory

Key of the SMS sender the message goes out as. The sender must be configured for the sending agent.

Example

2d6f4a1b9c35

Maximum Length :200Copied!

toJSON ArrayMandatory

Exactly one recipient.

Show Sub-Attributes

JSON Object

A single-send recipient.

Show Sub-Attributes

mobile_nostringMandatory

Recipient mobile number, including the country code.

Example

+919876543210

template_keyuuidOptional

Key of a pre-approved SMS template of the sender. Provide this or template_alias.

Example

6200ca60-921a-11f1-92c4-2a30dd3b833c

Maximum Length :500Copied!

template_aliasstringOptional

Alias of a pre-approved SMS template. Provide this or template_key.

Maximum Length :100Copied!

merge_infoobjectOptional

Key-value map that resolves the template's {{merge_tags}}. Tags left unresolved are sent literally in the message text.

Example

{
  "otp": "482913"
}

client_referencestringOptional

Client-supplied reference identifier, echoed in the SMS logs.

Example

otp-482913

Maximum Length :100Copied!

Sample Request

Curl

Java

Python

Deluge

Copied!

curl --request POST \
  --url https://cpaas.zoho.com/v1.1/sms \
  --header 'Authorization: Zoho-enczapikey {apiKey}' \
  --header 'content-type: application/json' \
  --data '{"template_key":"6200ca60-921a-11f1-92c4-2a30dd3b833c","client_reference":"otp-482913","merge_info":{"otp":"482913"},"to":[{"mobile_no":"+919876543210"}],"sender_key":"2d6f4a1b9c35"}'

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) throws Exception{

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://cpaas.zoho.com/v1.1/sms"))
        .header("content-type", "application/json")
        .header("Authorization", "Zoho-enczapikey {apiKey}")
        .method("POST", HttpRequest.BodyPublishers.ofString("{\"template_key\":\"6200ca60-921a-11f1-92c4-2a30dd3b833c\",\"client_reference\":\"otp-482913\",\"merge_info\":{\"otp\":\"482913\"},\"to\":[{\"mobile_no\":\"+919876543210\"}],\"sender_key\":\"2d6f4a1b9c35\"}"))
        .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")

payload = "{\"template_key\":\"6200ca60-921a-11f1-92c4-2a30dd3b833c\",\"client_reference\":\"otp-482913\",\"merge_info\":{\"otp\":\"482913\"},\"to\":[{\"mobile_no\":\"+919876543210\"}],\"sender_key\":\"2d6f4a1b9c35\"}"

headers = {
    'content-type': "application/json",
    'Authorization': "Zoho-enczapikey {apiKey}"
    }

conn.request("POST", "/v1.1/sms", payload, headers)

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

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


    headersMap = Map();
    headersMap.put("Authorization", "Zoho-enczapikey {apiKey}");
    headersMap.put("Content-Type", "application/json");
    headersMap.put("Accept", "application/json");

    data=Map();
    data.put("sender_key","2d6f4a1b9c35");
    data_to=List();
    data_to_item1=Map();
    data_to_item1.put("mobile_no","+919876543210");
    data_to.add(data_to_item1);
    data.put("to",data_to);
    data.put("template_key","6200ca60-921a-11f1-92c4-2a30dd3b833c");
    data.put("template_alias","value");
    data_merge_info=Map();
    data.put("merge_info",data_merge_info);
    data.put("client_reference","otp-482913");

    response = invokeUrl
    [
        url: "https://cpaas.zoho.com/v1.1/sms"
        type: POST
        headers: headersMap
        body: data
        connection: connection_name
    ]

    info response;

Sample Request Body

Template SMS with merge values

Copied!

  {
    "template_key": "6200ca60-921a-11f1-92c4-2a30dd3b833c",
    "client_reference": "otp-482913",
    "merge_info": {
      "otp": "482913"
    },
    "to": [
      {
        "mobile_no": "+919876543210"
      }
    ],
    "sender_key": "2d6f4a1b9c35"
  }

▼ Show full

Response Parameters

- HTTP code 200

Response Body - application/json

JSON Object

Success response returned when the SMS is queued for delivery.

Show Sub-Attributes

dataJSON Object

Show Sub-Attributes

codestring

Acceptance code.

Example

MSG_101

message_iduuid

Unique identifier of the message. Use it with the message-details API.

Example

7fff7400-b676-11f1-b0ad-b6d94062a427

messagestring

Example

Message queued

request_idstring

Unique identifier assigned to the send request.

Example

2d6f.14350939.i1.7fff7400-b676-11f1-b0ad-b6d94062a427.1a0c8d13740

statusstring

Example

success

- HTTP code 400

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

JSON Object

A single validation or denial detail inside the error envelope.

Show Sub-Attributes

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

JSON Object

A single validation or denial detail inside the error envelope.

Show Sub-Attributes

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 422

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

JSON Object

A single validation or denial detail inside the error envelope.

Show Sub-Attributes

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.

Sample Response: HTTP 200

Copied!

  {
    "data": {
      "code": "MSG_101",
      "message_id": "7fff7400-b676-11f1-b0ad-b6d94062a427",
      "message": "Message queued",
      "request_id": "2d6f.14350939.i1.7fff7400-b676-11f1-b0ad-b6d94062a427.1a0c8d13740"
    },
    "status": "success"
  }

▼ Show full

Sample Response: HTTP 400

sender_key missing

Copied!

  {
    "error": {
      "code": "TM_3301",
      "details": [
        {
          "code": "SERR_110",
          "message": "Parameter less than min occurrance",
          "target": "sender_key"
        }
      ],
      "message": "Bad Syntax"
    }
  }

▼ Show full

Neither template_key nor template_alias provided

Copied!

  {
    "error": {
      "code": "TM_3201",
      "details": [
        {
          "code": "GE_102",
          "message": "Mandatory field found empty",
          "target": "template_key | template_alias"
        }
      ],
      "message": "Mandatory Field missing"
    }
  }

▼ Show full

Malformed mobile number

Copied!

  {
    "error": {
      "code": "TM_3301",
      "details": [
        {
          "code": "SERR_102",
          "message": "Syntax error found",
          "target": "mobile_no"
        }
      ],
      "message": "Bad Syntax"
    }
  }

▼ Show full

Sample Response: HTTP 401

Template not associated with the sending agent

Copied!

  {
    "error": {
      "code": "TM_4001",
      "details": [
        {
          "code": "SMS_107",
          "message": "Invalid associated sender"
        }
      ],
      "message": "Access Denied"
    }
  }

▼ Show full

Invalid API token

Copied!

  {
    "error": {
      "code": "TM_4001",
      "details": [
        {
          "code": "SERR_157",
          "message": "Invalid API Token found"
        }
      ],
      "message": "Access Denied"
    }
  }

▼ Show full

Sample Response: HTTP 422

Copied!

  {
    "error": {
      "code": "TM_3501",
      "details": [
        {
          "code": "GE_122",
          "message": "Invalid value found",
          "target": "to"
        }
      ],
      "message": "Unprocessable Entity"
    }
  }

▼ Show full

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