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

• Production

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

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 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 (Mexico, without country code)

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

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

Example

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

401

Your key auth is not valid

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 doesn’t have credits available for sending

Example

{
  "status": false,
  "error": true,
  "description": "Your account doesn't have credits available for this, please contact your administrator"
}

406

Country or carrier not reachable or assigned to your account

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

Example

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

411

Your account doesn’t have multi-message sending enabled

Example

{
  "status": false,
  "error": true,
  "description": "Your account doesn't have multi-message sending enabled, 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);
    }
  }