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 single recipient, whose mobile_no must include the country code.

Endpoint

post /sms

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}. The agent and account are derived from the key.

- Path Parameters

message_iduuidMandatory

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

- 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_keystring(length <= 200)Mandatory

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

Maximum Length :200Copied!

toJSON ArrayMandatory

Exactly one recipient.

Show Sub-Attributes

object

A single-send recipient.

mobile_nostringMandatory

Recipient mobile number, including the country code.

template_keyuuid(length <= 500)Optional

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

Maximum Length :500Copied!

template_aliasstring(length <= 100)Optional

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.

client_referencestring(length <= 100)Optional

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

Maximum Length :100Copied!

Sample Request

Curl

Java

Python

Deluge

Copied!

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

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"))
        .header("content-type", "application/json")
        .header("Authorization", "REPLACE_KEY_VALUE")
        .method("POST", HttpRequest.BodyPublishers.ofString("{\"sender_key\":\"2d6f4a1b9c35\",\"to\":[{\"mobile_no\":\"919876543210\"}],\"template_key\":\"6200ca60-921a-11f1-92c4-2a30dd3b833c\",\"merge_info\":{\"otp\":\"482913\"},\"client_reference\":\"otp-482913\"}"))
        .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 = "{\"sender_key\":\"2d6f4a1b9c35\",\"to\":[{\"mobile_no\":\"919876543210\"}],\"template_key\":\"6200ca60-921a-11f1-92c4-2a30dd3b833c\",\"merge_info\":{\"otp\":\"482913\"},\"client_reference\":\"otp-482913\"}"

headers = {
    'content-type': "application/json",
    'Authorization': "REPLACE_KEY_VALUE"
    }

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

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

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


    headersMap = Map();
    headersMap.put("Authorization", "REPLACE_KEY_VALUE");
    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!

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

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

message_iduuid

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

messagestring

request_idstring

Unique identifier assigned to the send request.

statusstring

- 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

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 401

Response Body - application/json

JSON Object

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

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 422

Response Body - application/json

JSON Object

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

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!

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

Invalid API token

Copied!

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

▼ Show full

Template not associated with the sending agent

Copied!

  {
    "error": {
      "code": "TM_4001",
      "details": [
        {
          "code": "SMS_107",
          "message": "sms.api.invalid.associated.sender"
        }
      ],
      "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