Send SMS

Caution

For security reasons, please contact your Account Manager to provide you with an API host.

The host https://api.example.com not is a real endpoint.

POST

/v2/sms/send

Sends an SMS message using a JSON payload in the request body.

This method allows structured transmission of the SMS parameters and is recommended for server-to-server integrations.

Authorizations

BasicAuth

Use HTTP Basic Authentication to authorize requests.

The password is your API key, not your web portal password.

Example: Authorization: Basic WU9VUl9VU0VSTkFNRV9IRVJFOllPVVJfQVBJX1RPS0VOX0hFUkU=

(Where “YOUR_USERNAME_HERE:YOUR_API_TOKEN_HERE” is Base64-encoded)

Request Body ^required

JSON body containing the required parameters for sending an SMS.

object

msg

required

GSM-encoded message (max 160 characters)

string

>= 3 characters <= 160 characters

Hello World!

phone

required

10-digit destination phone number

string

/^\d{10}$/

8100001234

sender

Sender ID authorized by carrier (optional)

string

AWESOMEINC

id

External reference ID (optional)

string

my-external-id

Responses

200

SMS sent successfully

object

status

boolean

true

error

boolean

description

object

added_on

string format: date-time

2023-09-20 16:47:15

charge

number format: float

0.99

country

object

country

string

MEXICO

iso_code

string

MX

type

string

MOVIL

encoding

string

Allowed values: gsm unicode

gsm

id

integer

199999

job_id

string

199999

length

integer

12

message

string

Hello World!

number

string

8100001234

segments

integer

1

sender

string

AWESOMEINC

Example

{
  "status": true,
  "error": false,
  "description": {
    "added_on": "2023-09-20 16:47:15",
    "charge": 0.99,
    "country": {
      "country": "MEXICO",
      "iso_code": "MX",
      "type": "MOVIL"
    },
    "encoding": "gsm",
    "id": 199999,
    "job_id": 199999,
    "length": 12,
    "message": "Hello World!",
    "number": "8100001234",
    "segments": 1,
    "sender": "AWESOMEINC"
  }
}

400

Missing required parameters

object

status

boolean

error

boolean

true

message

string

Missing params, please verify or contact to support

Example

{
  "status": false,
  "error": true,
  "description": "Missing params, please verify or contact to support"
}

401

Your key auth is not valid

object

status

boolean

error

boolean

true

message

string

Your key auth is not valid, please check with your administrator to get the new key

Example

{
  "status": false,
  "error": true,
  "description": "Your key auth is not valid, please check with your administrator to get the new key"
}

402

Your account dont have credits availables for send

object

status

boolean

error

boolean

true

message

string

Your account dont have credits availables for send this, please contact your administrator

Example

{
  "status": false,
  "error": true,
  "description": "Your account dont have credits availables for send this, please contact your administrator"
}

406

Country or carrier not reachable or assigned to your account

object

status

boolean

error

boolean

true

message

string

Country or carrier not reachable or assigned to your account, please contact an administrator or support

Example

{
  "status": false,
  "error": true,
  "description": "Country or carrier not reachable or assigned to your account, please contact an administrator or support"
}

410

Failed to append to the queue, no need to resend

object

status

boolean

error

boolean

true

message

string

Failed to append to the queue, no need to resend

Example

{
  "status": false,
  "error": true,
  "description": "Failed to append to the queue, no need to resend"
}

411

Your account don’t have enabled for send multi messages

object

status

boolean

error

boolean

true

message

string

Your account don't have enabled for send multi messages, please contact your administrator

Example

{
  "status": false,
  "error": true,
  "description": "Your account don't have enabled for send multi messages, please contact your administrator"
}

Examples

Useful for guiding users to view code examples in different developer languages.

Bash

developer@developer:~#

curl -X POST "https://api.example.com/v2/sms/send" \
    -H "Accept: application/json" \
  -H "Connection: keep-alive" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <base64-encoded-credentials>" \
  -d '{"msg":"Hello World!","phone":"8100001234","sender":"AWESOMEINC","id":"my-external-id"}'

Node.js

example.js

  const fetch = require('node-fetch');

  fetch("https://api.example.com/v2/sms/send", {
    method: "POST",
    headers: {
  "Accept": "application/json",
  "Connection": "keep-alive",
  "Content-Type": "application/json",
  "Authorization": "Basic <base64-encoded-credentials>"
},
    body: JSON.stringify({
  "msg": "Hello World!",
  "phone": "8100001234",
  "sender": "AWESOMEINC",
  "id": "my-external-id"
})
  })
    .then(res => res.json())
    .then(console.log)
    .catch(console.error);

PHP

example.php

  <?php
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.example.com/v2/sms/send",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
    "Accept: application/json",
    "Connection: keep-alive",
    "Content-Type: application/json",
    "Authorization: Basic <base64-encoded-credentials>"
    ],
    CURLOPT_POSTFIELDS => json_encode({
  "msg": "Hello World!",
  "phone": "8100001234",
  "sender": "AWESOMEINC",
  "id": "my-external-id"
})
  ]);

  $response = curl_exec($curl);
  curl_close($curl);
  echo $response;
  ?>

C-Sharp

example.cs

  using System.Net.Http;
  using System.Text;
  using System.Threading.Tasks;

  var client = new HttpClient();
  var request = new HttpRequestMessage(HttpMethod.POST, "https://api.example.com/v2/sms/send") {
    Content = new StringContent("{
  \"msg\": \"Hello World!\",
  \"phone\": \"8100001234\",
  \"sender\": \"AWESOMEINC\",
  \"id\": \"my-external-id\"
}", Encoding.UTF8, "application/json")
  };
  request.Headers.Add("Accept", "application/json");
request.Headers.Add("Connection", "keep-alive");
request.Headers.Add("Content-Type", "application/json");
request.Headers.Add("Authorization", "Basic <base64-encoded-credentials>");
  var response = await client.SendAsync(request);
  var responseBody = await response.Content.ReadAsStringAsync();
  Console.WriteLine(responseBody);

Python

example.py

  import requests
  import json

  url = "https://api.example.com/v2/sms/send"
  headers = {
    "Accept": "application/json",
  "Connection": "keep-alive",
  "Content-Type": "application/json",
  "Authorization": "Basic <base64-encoded-credentials>"
  }
  data = {
  "msg": "Hello World!",
  "phone": "8100001234",
  "sender": "AWESOMEINC",
  "id": "my-external-id"
}

  response = requests.post(url, headers=headers, json=data)
  print(response.text)

Java

example.java

  import java.io.OutputStream;
  import java.net.HttpURLConnection;
  import java.net.URL;
  import java.nio.charset.StandardCharsets;

  public class ApiExample {
    public static void main(String[] args) throws Exception {
      URL url = new URL("https://api.example.com/v2/sms/send");
      HttpURLConnection conn = (HttpURLConnection) url.openConnection();
      conn.setRequestMethod("POST");
      conn.setDoOutput(true);
      conn.setRequestProperty("Accept", "application/json");
    conn.setRequestProperty("Connection", "keep-alive");
    conn.setRequestProperty("Content-Type", "application/json");
    conn.setRequestProperty("Authorization", "Basic <base64-encoded-credentials>");

      String jsonInputString = "{\"msg\":\"Hello World!\",\"phone\":\"8100001234\",\"sender\":\"AWESOMEINC\",\"id\":\"my-external-id\"}";
      try(OutputStream os = conn.getOutputStream()) {
          byte[] input = jsonInputString.getBytes(StandardCharsets.UTF_8);
          os.write(input, 0, input.length);
      }

      int code = conn.getResponseCode();
      System.out.println("Response code: " + code);
    }
  }