SMS REST API (Legacy)

Send SMS to your customers with a simple, reliable REST API. This legacy endpoint supports all the messaging features you need—from basic texts to scheduled sends, concatenated messages, and bulk broadcasting.

Security Update

Starting from January 15th, 2026, HTTP connections are accepted only over TLS (HTTPS). Non-TLS connections will be rejected. GET requests and form-encoded POST requests will no longer be accepted—only POST with JSON payload over HTTPS is supported.

Base URLs

Choose the endpoint based on your account type:

Legacy customers:

https://secure.agiletelecom.com/services/

New customers:

https://http-api.agiletelecom.com/services/

Authentication

Add one of these authentication methods to your request headers:

Basic Authentication

Authorization: Basic <base64_encoded_credentials>

API Key (Recommended)

X-Api-Key: YOUR_API_KEY

Send SMS

Send SMS messages to one or multiple recipients in a single API call.

Endpoint

POST /sms/send

Required Headers

Content-Type: application/json

Request Body

{
  "globalId": "string",
  "maxIdLen": 64,
  "enableConcatenated": true,
  "enableUnicode": true,
  "enableDelivery": true,
  "simulation": false,
  "messages": [
    {
      "ids": ["string"],
      "destinations": ["+393351234567"],
      "sender": "string",
      "body": "string",
      "hexBody": false,
      "udhData": "string",
      "scheduling": "2025-12-08 06:00:00.002+0200"
    }
  ]
}

Request Parameters

Field	Type	Required	Default	Description
globalId	string	No	--	Unique identifier for this send request, useful for tracking and correlating responses
maxIdLen	integer	No	64	Maximum length (characters) of message IDs
enableConcatenated	boolean	No	true	Automatically split long messages into multiple SMS parts
enableUnicode	boolean	No	true	Support special characters and non-ASCII text
enableDelivery	boolean	No	true	Receive delivery notifications via webhook
simulation	boolean	No	false	Test your request without actually sending messages
messages	array	Yes	--	Array of message objects to send

Message Parameters

Field	Type	Required	Default	Description
destinations	array	Yes	--	Phone numbers in international format (include country code)
ids	array	No	--	Unique identifiers for tracking each message
sender	string	Yes	--	Sender ID (alphanumeric max 11 chars, or numeric max 16 digits)
body	string	Yes	--	Message content (text or HEX if hexBody=true)
hexBody	boolean	No	false	Set true if body is HEX-encoded
udhData	string	No	--	User Data Header for special message formatting
scheduling	string	No	--	Delivery time in format "yyyy-MM-dd HH:mm:ss.SSSZ"

Check Account Credit

Verify your remaining account balance before sending.

Endpoint

GET /sms/credit

Success Response

{
  "credit": 10.324
}

Response Formats

Success Response (2XX)

When your request succeeds, you'll receive:

{
  "globalId": "f9b865ef-5ce3-4e44-b65c-615fd71bbd09",
  "processedMessages": 2,
  "processedSmsParts": 4,
  "credit": 10.324
}

Field	Type	Description
globalId	string	Echo of your global ID from the request
processedMessages	integer	Number of message objects accepted
processedSmsParts	integer	Total SMS parts to be sent (higher if concatenation occurs)
credit	double	Your remaining credit in EUR

Client Errors (4XX)

Validation or authentication issues:

{
  "status": "fail",
  "data": {
    "body": "Missing message body(ies)",
    "number": "Wrong destination number(s)"
  },
  "code": 6
}

Field	Type	Description
status	string	Always "fail" for 4XX responses
data	object/string	Details about which fields failed validation
code	integer	Error code (see table below)

Server Errors (5XX)

Service unavailability or timeouts:

{
  "status": "error",
  "message": "Number check service unavailable",
  "code": 9
}

Field	Type	Description
status	string	Always "error" for 5XX responses
message	string	Human-readable error description
code	integer	Error code (see table below)

Error Codes

Code	Description
1	Wrong credentials
2	Insufficient credit
3	Destination not allowed
4	Unknown error
5	Destination number too short
6	Destination number too long
7	Invalid destination number
8	Server error
9	Service timeout
10	Wrong global ID length
26	Sender alias not allowed
100	Source IP not allowed

Code Examples

Simple SMS

Send a basic text message to a single recipient.

curl -X POST https://secure.agiletelecom.com/services/sms/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "messages": [
      {
        "destinations": ["+393471234567"],
        "sender": "MyApp",
        "body": "Hello! This is your test message from Agile Telecom."
      }
    ]
  }'

import requests
import json

url = "https://secure.agiletelecom.com/services/sms/send"
headers = {
    "Content-Type": "application/json",
    "X-Api-Key": "YOUR_API_KEY"
}
payload = {
    "messages": [
        {
            "destinations": ["+393471234567"],
            "sender": "MyApp",
            "body": "Hello! This is your test message from Agile Telecom."
        }
    ]
}

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

const https = require('https');

const data = JSON.stringify({
  messages: [
    {
      destinations: ["+393471234567"],
      sender: "MyApp",
      body: "Hello! This is your test message from Agile Telecom."
    }
  ]
});

const options = {
  hostname: 'secure.agiletelecom.com',
  path: '/services/sms/send',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Length': data.length
  }
};

const req = https.request(options, (res) => {
  let responseData = '';
  res.on('data', (chunk) => { responseData += chunk; });
  res.on('end', () => { console.log(JSON.parse(responseData)); });
});

req.write(data);
req.end();

<?php
$url = "https://secure.agiletelecom.com/services/sms/send";
$apiKey = "YOUR_API_KEY";

$payload = json_encode([
    "messages" => [
        [
            "destinations" => ["+393471234567"],
            "sender" => "MyApp",
            "body" => "Hello! This is your test message from Agile Telecom."
        ]
    ]
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "X-Api-Key: {$apiKey}"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
echo json_encode(json_decode($response), JSON_PRETTY_PRINT);
curl_close($ch);
?>

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class SendSMS {
    public static void main(String[] args) throws Exception {
        String url = "https://secure.agiletelecom.com/services/sms/send";
        String apiKey = "YOUR_API_KEY";
        
        String jsonPayload = """
            {
              "messages": [
                {
                  "destinations": ["+393471234567"],
                  "sender": "MyApp",
                  "body": "Hello! This is your test message from Agile Telecom."
                }
              ]
            }
            """;
        
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Content-Type", "application/json")
            .header("X-Api-Key", apiKey)
            .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
            .build();
        
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

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

class Program {
    static async Task Main() {
        string url = "https://secure.agiletelecom.com/services/sms/send";
        string apiKey = "YOUR_API_KEY";
        
        string jsonPayload = @"{
            ""messages"": [
                {
                    ""destinations"": [""+393471234567""],
                    ""sender"": ""MyApp"",
                    ""body"": ""Hello! This is your test message from Agile Telecom.""
                }
            ]
        }";
        
        using (var client = new HttpClient()) {
            client.DefaultRequestHeaders.Add("X-Api-Key", apiKey);
            var content = new StringContent(jsonPayload, Encoding.UTF8, "application/json");
            
            var response = await client.PostAsync(url, content);
            var responseContent = await response.Content.ReadAsStringAsync();
            Console.WriteLine(responseContent);
        }
    }
}

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://secure.agiletelecom.com/services/sms/send"
	apiKey := "YOUR_API_KEY"
	
	payload := []byte(`{
		"messages": [
			{
				"destinations": ["+393471234567"],
				"sender": "MyApp",
				"body": "Hello! This is your test message from Agile Telecom."
			}
		]
	}`)
	
	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-Api-Key", apiKey)
	
	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()
	
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

require 'net/https'
require 'json'
require 'uri'

url = URI("https://secure.agiletelecom.com/services/sms/send")
api_key = "YOUR_API_KEY"

payload = {
  messages: [
    {
      destinations: ["+393471234567"],
      sender: "MyApp",
      body: "Hello! This is your test message from Agile Telecom."
    }
  ]
}.to_json

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url.path)
request["Content-Type"] = "application/json"
request["X-Api-Key"] = api_key
request.body = payload

response = http.request(request)
puts response.body

SMS with Custom Message ID

Track individual messages with unique IDs for delivery reporting.

curl -X POST https://secure.agiletelecom.com/services/sms/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "messages": [
      {
        "ids": ["msg-001-20260408"],
        "destinations": ["+393471234567"],
        "sender": "MyApp",
        "body": "Order confirmed! Your purchase reference is ORD-2026-4521."
      }
    ]
  }'

import requests

response = requests.post(
    "https://secure.agiletelecom.com/services/sms/send",
    headers={
        "Content-Type": "application/json",
        "X-Api-Key": "YOUR_API_KEY"
    },
    json={
        "messages": [
            {
                "ids": ["msg-001-20260408"],
                "destinations": ["+393471234567"],
                "sender": "MyApp",
                "body": "Order confirmed! Your purchase reference is ORD-2026-4521."
            }
        ]
    }
)
print(response.json())

const https = require('https');

const data = JSON.stringify({
  messages: [
    {
      ids: ["msg-001-20260408"],
      destinations: ["+393471234567"],
      sender: "MyApp",
      body: "Order confirmed! Your purchase reference is ORD-2026-4521."
    }
  ]
});

const req = https.request({
  hostname: 'secure.agiletelecom.com',
  path: '/services/sms/send',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Length': data.length
  }
}, (res) => {
  let responseData = '';
  res.on('data', (chunk) => { responseData += chunk; });
  res.on('end', () => { console.log(JSON.parse(responseData)); });
});

req.write(data);
req.end();

<?php
$payload = json_encode([
    "messages" => [
        [
            "ids" => ["msg-001-20260408"],
            "destinations" => ["+393471234567"],
            "sender" => "MyApp",
            "body" => "Order confirmed! Your purchase reference is ORD-2026-4521."
        ]
    ]
]);

$ch = curl_init("https://secure.agiletelecom.com/services/sms/send");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "X-Api-Key: YOUR_API_KEY"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);
echo json_decode($response, true);
?>

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
String json = """
    {
      "messages": [
        {
          "ids": ["msg-001-20260408"],
          "destinations": ["+393471234567"],
          "sender": "MyApp",
          "body": "Order confirmed! Your purchase reference is ORD-2026-4521."
        }
      ]
    }
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://secure.agiletelecom.com/services/sms/send"))
    .header("Content-Type", "application/json")
    .header("X-Api-Key", "YOUR_API_KEY")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

using (var client = new HttpClient()) {
    client.DefaultRequestHeaders.Add("X-Api-Key", "YOUR_API_KEY");
    
    var json = @"{
        ""messages"": [
            {
                ""ids"": [""msg-001-20260408""],
                ""destinations"": [""+393471234567""],
                ""sender"": ""MyApp"",
                ""body"": ""Order confirmed! Your purchase reference is ORD-2026-4521.""
            }
        ]
    }";
    
    var content = new StringContent(json, Encoding.UTF8, "application/json");
    var response = await client.PostAsync(
        "https://secure.agiletelecom.com/services/sms/send", 
        content
    );
    var result = await response.Content.ReadAsStringAsync();
    Console.WriteLine(result);
}

package main

import (
	"bytes"
	"io"
	"net/http"
)

func main() {
	payload := []byte(`{
		"messages": [
			{
				"ids": ["msg-001-20260408"],
				"destinations": ["+393471234567"],
				"sender": "MyApp",
				"body": "Order confirmed! Your purchase reference is ORD-2026-4521."
			}
		]
	}`)
	
	req, _ := http.NewRequest("POST", 
		"https://secure.agiletelecom.com/services/sms/send", 
		bytes.NewBuffer(payload))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-Api-Key", "YOUR_API_KEY")
	
	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()
	
	body, _ := io.ReadAll(resp.Body)
	println(string(body))
}

require 'net/https'
require 'json'

payload = {
  messages: [
    {
      ids: ["msg-001-20260408"],
      destinations: ["+393471234567"],
      sender: "MyApp",
      body: "Order confirmed! Your purchase reference is ORD-2026-4521."
    }
  ]
}.to_json

uri = URI("https://secure.agiletelecom.com/services/sms/send")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.path)
request["Content-Type"] = "application/json"
request["X-Api-Key"] = "YOUR_API_KEY"
request.body = payload

response = http.request(request)
puts JSON.parse(response.body)

Long Message (Concatenated SMS)

Automatically split long messages into multiple SMS parts. Requires enableConcatenated: true.

curl -X POST https://secure.agiletelecom.com/services/sms/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "enableConcatenated": true,
    "messages": [
      {
        "destinations": ["+393471234567"],
        "sender": "Newsletter",
        "body": "Stay healthy this summer with our top wellness tips. Drink plenty of water throughout the day to stay hydrated. Always wear broad-spectrum sunscreen (SPF 30+) to protect your skin from UV damage. Include fresh fruits and vegetables in every meal. Exercise for at least 30 minutes during cooler morning or evening hours."
      }
    ]
  }'

import requests

response = requests.post(
    "https://secure.agiletelecom.com/services/sms/send",
    headers={
        "Content-Type": "application/json",
        "X-Api-Key": "YOUR_API_KEY"
    },
    json={
        "enableConcatenated": True,
        "messages": [
            {
                "destinations": ["+393471234567"],
                "sender": "Newsletter",
                "body": "Stay healthy this summer with our top wellness tips. Drink plenty of water throughout the day to stay hydrated. Always wear broad-spectrum sunscreen (SPF 30+) to protect your skin from UV damage. Include fresh fruits and vegetables in every meal. Exercise for at least 30 minutes during cooler morning or evening hours."
            }
        ]
    }
)
print(response.json())

const https = require('https');

const data = JSON.stringify({
  enableConcatenated: true,
  messages: [
    {
      destinations: ["+393471234567"],
      sender: "Newsletter",
      body: "Stay healthy this summer with our top wellness tips. Drink plenty of water throughout the day to stay hydrated. Always wear broad-spectrum sunscreen (SPF 30+) to protect your skin from UV damage. Include fresh fruits and vegetables in every meal. Exercise for at least 30 minutes during cooler morning or evening hours."
    }
  ]
});

const req = https.request({
  hostname: 'secure.agiletelecom.com',
  path: '/services/sms/send',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Length': data.length
  }
}, (res) => {
  let responseData = '';
  res.on('data', (chunk) => { responseData += chunk; });
  res.on('end', () => { console.log(JSON.parse(responseData)); });
});

req.write(data);
req.end();

<?php
$payload = json_encode([
    "enableConcatenated" => true,
    "messages" => [
        [
            "destinations" => ["+393471234567"],
            "sender" => "Newsletter",
            "body" => "Stay healthy this summer with our top wellness tips. Drink plenty of water throughout the day to stay hydrated. Always wear broad-spectrum sunscreen (SPF 30+) to protect your skin from UV damage. Include fresh fruits and vegetables in every meal. Exercise for at least 30 minutes during cooler morning or evening hours."
        ]
    ]
]);

$ch = curl_init("https://secure.agiletelecom.com/services/sms/send");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "X-Api-Key: YOUR_API_KEY"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);
print_r(json_decode($response, true));
?>

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
String json = """
    {
      "enableConcatenated": true,
      "messages": [
        {
          "destinations": ["+393471234567"],
          "sender": "Newsletter",
          "body": "Stay healthy this summer with our top wellness tips. Drink plenty of water throughout the day to stay hydrated. Always wear broad-spectrum sunscreen (SPF 30+) to protect your skin from UV damage. Include fresh fruits and vegetables in every meal. Exercise for at least 30 minutes during cooler morning or evening hours."
        }
      ]
    }
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://secure.agiletelecom.com/services/sms/send"))
    .header("Content-Type", "application/json")
    .header("X-Api-Key", "YOUR_API_KEY")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

using (var client = new HttpClient()) {
    client.DefaultRequestHeaders.Add("X-Api-Key", "YOUR_API_KEY");
    
    var json = @"{
        ""enableConcatenated"": true,
        ""messages"": [
            {
                ""destinations"": [""+393471234567""],
                ""sender"": ""Newsletter"",
                ""body"": ""Stay healthy this summer with our top wellness tips. Drink plenty of water throughout the day to stay hydrated. Always wear broad-spectrum sunscreen (SPF 30+) to protect your skin from UV damage. Include fresh fruits and vegetables in every meal. Exercise for at least 30 minutes during cooler morning or evening hours.""
            }
        ]
    }";
    
    var content = new StringContent(json, Encoding.UTF8, "application/json");
    var response = await client.PostAsync(
        "https://secure.agiletelecom.com/services/sms/send", 
        content
    );
    Console.WriteLine(await response.Content.ReadAsStringAsync());
}

package main

import (
	"bytes"
	"io"
	"net/http"
)

func main() {
	payload := []byte(`{
		"enableConcatenated": true,
		"messages": [
			{
				"destinations": ["+393471234567"],
				"sender": "Newsletter",
				"body": "Stay healthy this summer with our top wellness tips. Drink plenty of water throughout the day to stay hydrated. Always wear broad-spectrum sunscreen (SPF 30+) to protect your skin from UV damage. Include fresh fruits and vegetables in every meal. Exercise for at least 30 minutes during cooler morning or evening hours."
			}
		]
	}`)
	
	req, _ := http.NewRequest("POST", 
		"https://secure.agiletelecom.com/services/sms/send", 
		bytes.NewBuffer(payload))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-Api-Key", "YOUR_API_KEY")
	
	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()
	
	body, _ := io.ReadAll(resp.Body)
	println(string(body))
}

require 'net/https'
require 'json'

payload = {
  enableConcatenated: true,
  messages: [
    {
      destinations: ["+393471234567"],
      sender: "Newsletter",
      body: "Stay healthy this summer with our top wellness tips. Drink plenty of water throughout the day to stay hydrated. Always wear broad-spectrum sunscreen (SPF 30+) to protect your skin from UV damage. Include fresh fruits and vegetables in every meal. Exercise for at least 30 minutes during cooler morning or evening hours."
    }
  ]
}.to_json

uri = URI("https://secure.agiletelecom.com/services/sms/send")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.path)
request["Content-Type"] = "application/json"
request["X-Api-Key"] = "YOUR_API_KEY"
request.body = payload

response = http.request(request)
puts JSON.parse(response.body)

Unicode Message

Send messages with special characters, accents, and non-ASCII text.

curl -X POST https://secure.agiletelecom.com/services/sms/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "enableUnicode": true,
    "messages": [
      {
        "destinations": ["+393471234567"],
        "sender": "WeatherAlert",
        "body": "ATTENZIONE: Domani temperature fino a 38°C. Rimani idratato e stai al riparo dalle 12:00 alle 17:00."
      }
    ]
  }'

import requests

response = requests.post(
    "https://secure.agiletelecom.com/services/sms/send",
    headers={
        "Content-Type": "application/json",
        "X-Api-Key": "YOUR_API_KEY"
    },
    json={
        "enableUnicode": True,
        "messages": [
            {
                "destinations": ["+393471234567"],
                "sender": "WeatherAlert",
                "body": "ATTENZIONE: Domani temperature fino a 38°C. Rimani idratato e stai al riparo dalle 12:00 alle 17:00."
            }
        ]
    }
)
print(response.json())

const https = require('https');

const data = JSON.stringify({
  enableUnicode: true,
  messages: [
    {
      destinations: ["+393471234567"],
      sender: "WeatherAlert",
      body: "ATTENZIONE: Domani temperature fino a 38°C. Rimani idratato e stai al riparo dalle 12:00 alle 17:00."
    }
  ]
});

const req = https.request({
  hostname: 'secure.agiletelecom.com',
  path: '/services/sms/send',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Length': data.length
  }
}, (res) => {
  let responseData = '';
  res.on('data', (chunk) => { responseData += chunk; });
  res.on('end', () => { console.log(JSON.parse(responseData)); });
});

req.write(data);
req.end();

<?php
$payload = json_encode([
    "enableUnicode" => true,
    "messages" => [
        [
            "destinations" => ["+393471234567"],
            "sender" => "WeatherAlert",
            "body" => "ATTENZIONE: Domani temperature fino a 38°C. Rimani idratato e stai al riparo dalle 12:00 alle 17:00."
        ]
    ]
]);

$ch = curl_init("https://secure.agiletelecom.com/services/sms/send");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "X-Api-Key: YOUR_API_KEY"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

echo json_encode(json_decode(curl_exec($ch)), JSON_PRETTY_PRINT);
curl_close($ch);
?>

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
String json = """
    {
      "enableUnicode": true,
      "messages": [
        {
          "destinations": ["+393471234567"],
          "sender": "WeatherAlert",
          "body": "ATTENZIONE: Domani temperature fino a 38°C. Rimani idratato e stai al riparo dalle 12:00 alle 17:00."
        }
      ]
    }
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://secure.agiletelecom.com/services/sms/send"))
    .header("Content-Type", "application/json")
    .header("X-Api-Key", "YOUR_API_KEY")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

using (var client = new HttpClient()) {
    client.DefaultRequestHeaders.Add("X-Api-Key", "YOUR_API_KEY");
    
    var json = @"{
        ""enableUnicode"": true,
        ""messages"": [
            {
                ""destinations"": [""+393471234567""],
                ""sender"": ""WeatherAlert"",
                ""body"": ""ATTENZIONE: Domani temperature fino a 38°C. Rimani idratato e stai al riparo dalle 12:00 alle 17:00.""
            }
        ]
    }";
    
    var content = new StringContent(json, Encoding.UTF8, "application/json");
    var response = await client.PostAsync(
        "https://secure.agiletelecom.com/services/sms/send", 
        content
    );
    Console.WriteLine(await response.Content.ReadAsStringAsync());
}

package main

import (
	"bytes"
	"io"
	"net/http"
)

func main() {
	payload := []byte(`{
		"enableUnicode": true,
		"messages": [
			{
				"destinations": ["+393471234567"],
				"sender": "WeatherAlert",
				"body": "ATTENZIONE: Domani temperature fino a 38°C. Rimani idratato e stai al riparo dalle 12:00 alle 17:00."
			}
		]
	}`)
	
	req, _ := http.NewRequest("POST", 
		"https://secure.agiletelecom.com/services/sms/send", 
		bytes.NewBuffer(payload))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-Api-Key", "YOUR_API_KEY")
	
	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()
	
	body, _ := io.ReadAll(resp.Body)
	println(string(body))
}

require 'net/https'
require 'json'

payload = {
  enableUnicode: true,
  messages: [
    {
      destinations: ["+393471234567"],
      sender: "WeatherAlert",
      body: "ATTENZIONE: Domani temperature fino a 38°C. Rimani idratato e stai al riparo dalle 12:00 alle 17:00."
    }
  ]
}.to_json

uri = URI("https://secure.agiletelecom.com/services/sms/send")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.path)
request["Content-Type"] = "application/json"
request["X-Api-Key"] = "YOUR_API_KEY"
request.body = payload

response = http.request(request)
puts JSON.parse(response.body)

Scheduled SMS

Send a message at a specific time in the future.

curl -X POST https://secure.agiletelecom.com/services/sms/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "messages": [
      {
        "destinations": ["+393471234567"],
        "sender": "ReminderBot",
        "body": "Reminder: Your appointment is tomorrow at 10:00 AM. Please arrive 10 minutes early.",
        "scheduling": "2026-04-09 19:30:00.000+0200"
      }
    ]
  }'

import requests

response = requests.post(
    "https://secure.agiletelecom.com/services/sms/send",
    headers={
        "Content-Type": "application/json",
        "X-Api-Key": "YOUR_API_KEY"
    },
    json={
        "messages": [
            {
                "destinations": ["+393471234567"],
                "sender": "ReminderBot",
                "body": "Reminder: Your appointment is tomorrow at 10:00 AM. Please arrive 10 minutes early.",
                "scheduling": "2026-04-09 19:30:00.000+0200"
            }
        ]
    }
)
print(response.json())

const https = require('https');

const data = JSON.stringify({
  messages: [
    {
      destinations: ["+393471234567"],
      sender: "ReminderBot",
      body: "Reminder: Your appointment is tomorrow at 10:00 AM. Please arrive 10 minutes early.",
      scheduling: "2026-04-09 19:30:00.000+0200"
    }
  ]
});

const req = https.request({
  hostname: 'secure.agiletelecom.com',
  path: '/services/sms/send',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Length': data.length
  }
}, (res) => {
  let responseData = '';
  res.on('data', (chunk) => { responseData += chunk; });
  res.on('end', () => { console.log(JSON.parse(responseData)); });
});

req.write(data);
req.end();

<?php
$payload = json_encode([
    "messages" => [
        [
            "destinations" => ["+393471234567"],
            "sender" => "ReminderBot",
            "body" => "Reminder: Your appointment is tomorrow at 10:00 AM. Please arrive 10 minutes early.",
            "scheduling" => "2026-04-09 19:30:00.000+0200"
        ]
    ]
]);

$ch = curl_init("https://secure.agiletelecom.com/services/sms/send");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "X-Api-Key: YOUR_API_KEY"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

echo json_encode(json_decode(curl_exec($ch)), JSON_PRETTY_PRINT);
curl_close($ch);
?>

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
String json = """
    {
      "messages": [
        {
          "destinations": ["+393471234567"],
          "sender": "ReminderBot",
          "body": "Reminder: Your appointment is tomorrow at 10:00 AM. Please arrive 10 minutes early.",
          "scheduling": "2026-04-09 19:30:00.000+0200"
        }
      ]
    }
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://secure.agiletelecom.com/services/sms/send"))
    .header("Content-Type", "application/json")
    .header("X-Api-Key", "YOUR_API_KEY")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

using (var client = new HttpClient()) {
    client.DefaultRequestHeaders.Add("X-Api-Key", "YOUR_API_KEY");
    
    var json = @"{
        ""messages"": [
            {
                ""destinations"": [""+393471234567""],
                ""sender"": ""ReminderBot"",
                ""body"": ""Reminder: Your appointment is tomorrow at 10:00 AM. Please arrive 10 minutes early."",
                ""scheduling"": ""2026-04-09 19:30:00.000+0200""
            }
        ]
    }";
    
    var content = new StringContent(json, Encoding.UTF8, "application/json");
    var response = await client.PostAsync(
        "https://secure.agiletelecom.com/services/sms/send", 
        content
    );
    Console.WriteLine(await response.Content.ReadAsStringAsync());
}

package main

import (
	"bytes"
	"io"
	"net/http"
)

func main() {
	payload := []byte(`{
		"messages": [
			{
				"destinations": ["+393471234567"],
				"sender": "ReminderBot",
				"body": "Reminder: Your appointment is tomorrow at 10:00 AM. Please arrive 10 minutes early.",
				"scheduling": "2026-04-09 19:30:00.000+0200"
			}
		]
	}`)
	
	req, _ := http.NewRequest("POST", 
		"https://secure.agiletelecom.com/services/sms/send", 
		bytes.NewBuffer(payload))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-Api-Key", "YOUR_API_KEY")
	
	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()
	
	body, _ := io.ReadAll(resp.Body)
	println(string(body))
}

require 'net/https'
require 'json'

payload = {
  messages: [
    {
      destinations: ["+393471234567"],
      sender: "ReminderBot",
      body: "Reminder: Your appointment is tomorrow at 10:00 AM. Please arrive 10 minutes early.",
      scheduling: "2026-04-09 19:30:00.000+0200"
    }
  ]
}.to_json

uri = URI("https://secure.agiletelecom.com/services/sms/send")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.path)
request["Content-Type"] = "application/json"
request["X-Api-Key"] = "YOUR_API_KEY"
request.body = payload

response = http.request(request)
puts JSON.parse(response.body)

Bulk SMS to Multiple Recipients

Send the same message to multiple phone numbers in one request.

curl -X POST https://secure.agiletelecom.com/services/sms/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "messages": [
      {
        "ids": ["bulk-promo-001", "bulk-promo-002"],
        "destinations": ["+393471234567", "+393471234568"],
        "sender": "PromoShop",
        "body": "Limited-time offer: Buy 2 get 1 free on all summer items! Valid until Sunday midnight."
      }
    ]
  }'

import requests

response = requests.post(
    "https://secure.agiletelecom.com/services/sms/send",
    headers={
        "Content-Type": "application/json",
        "X-Api-Key": "YOUR_API_KEY"
    },
    json={
        "messages": [
            {
                "ids": ["bulk-promo-001", "bulk-promo-002"],
                "destinations": ["+393471234567", "+393471234568"],
                "sender": "PromoShop",
                "body": "Limited-time offer: Buy 2 get 1 free on all summer items! Valid until Sunday midnight."
            }
        ]
    }
)
print(response.json())

const https = require('https');

const data = JSON.stringify({
  messages: [
    {
      ids: ["bulk-promo-001", "bulk-promo-002"],
      destinations: ["+393471234567", "+393471234568"],
      sender: "PromoShop",
      body: "Limited-time offer: Buy 2 get 1 free on all summer items! Valid until Sunday midnight."
    }
  ]
});

const req = https.request({
  hostname: 'secure.agiletelecom.com',
  path: '/services/sms/send',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Length': data.length
  }
}, (res) => {
  let responseData = '';
  res.on('data', (chunk) => { responseData += chunk; });
  res.on('end', () => { console.log(JSON.parse(responseData)); });
});

req.write(data);
req.end();

<?php
$payload = json_encode([
    "messages" => [
        [
            "ids" => ["bulk-promo-001", "bulk-promo-002"],
            "destinations" => ["+393471234567", "+393471234568"],
            "sender" => "PromoShop",
            "body" => "Limited-time offer: Buy 2 get 1 free on all summer items! Valid until Sunday midnight."
        ]
    ]
]);

$ch = curl_init("https://secure.agiletelecom.com/services/sms/send");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "X-Api-Key: YOUR_API_KEY"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

echo json_encode(json_decode(curl_exec($ch)), JSON_PRETTY_PRINT);
curl_close($ch);
?>

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
String json = """
    {
      "messages": [
        {
          "ids": ["bulk-promo-001", "bulk-promo-002"],
          "destinations": ["+393471234567", "+393471234568"],
          "sender": "PromoShop",
          "body": "Limited-time offer: Buy 2 get 1 free on all summer items! Valid until Sunday midnight."
        }
      ]
    }
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://secure.agiletelecom.com/services/sms/send"))
    .header("Content-Type", "application/json")
    .header("X-Api-Key", "YOUR_API_KEY")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

using (var client = new HttpClient()) {
    client.DefaultRequestHeaders.Add("X-Api-Key", "YOUR_API_KEY");
    
    var json = @"{
        ""messages"": [
            {
                ""ids"": [""bulk-promo-001"", ""bulk-promo-002""],
                ""destinations"": [""+393471234567"", ""+393471234568""],
                ""sender"": ""PromoShop"",
                ""body"": ""Limited-time offer: Buy 2 get 1 free on all summer items! Valid until Sunday midnight.""
            }
        ]
    }";
    
    var content = new StringContent(json, Encoding.UTF8, "application/json");
    var response = await client.PostAsync(
        "https://secure.agiletelecom.com/services/sms/send", 
        content
    );
    Console.WriteLine(await response.Content.ReadAsStringAsync());
}

package main

import (
	"bytes"
	"io"
	"net/http"
)

func main() {
	payload := []byte(`{
		"messages": [
			{
				"ids": ["bulk-promo-001", "bulk-promo-002"],
				"destinations": ["+393471234567", "+393471234568"],
				"sender": "PromoShop",
				"body": "Limited-time offer: Buy 2 get 1 free on all summer items! Valid until Sunday midnight."
			}
		]
	}`)
	
	req, _ := http.NewRequest("POST", 
		"https://secure.agiletelecom.com/services/sms/send", 
		bytes.NewBuffer(payload))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-Api-Key", "YOUR_API_KEY")
	
	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()
	
	body, _ := io.ReadAll(resp.Body)
	println(string(body))
}

require 'net/https'
require 'json'

payload = {
  messages: [
    {
      ids: ["bulk-promo-001", "bulk-promo-002"],
      destinations: ["+393471234567", "+393471234568"],
      sender: "PromoShop",
      body: "Limited-time offer: Buy 2 get 1 free on all summer items! Valid until Sunday midnight."
    }
  ]
}.to_json

uri = URI("https://secure.agiletelecom.com/services/sms/send")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.path)
request["Content-Type"] = "application/json"
request["X-Api-Key"] = "YOUR_API_KEY"
request.body = payload

response = http.request(request)
puts JSON.parse(response.body)

Check Account Credit

Verify your current credit balance before sending campaigns.

curl -X GET https://secure.agiletelecom.com/services/sms/credit \
  -H "X-Api-Key: YOUR_API_KEY"

import requests

response = requests.get(
    "https://secure.agiletelecom.com/services/sms/credit",
    headers={
        "X-Api-Key": "YOUR_API_KEY"
    }
)
print(response.json())

const https = require('https');

const options = {
  hostname: 'secure.agiletelecom.com',
  path: '/services/sms/credit',
  method: 'GET',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY'
  }
};

https.request(options, (res) => {
  let data = '';
  res.on('data', (chunk) => { data += chunk; });
  res.on('end', () => { console.log(JSON.parse(data)); });
}).end();

<?php
$ch = curl_init("https://secure.agiletelecom.com/services/sms/credit");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-Api-Key: YOUR_API_KEY"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);
echo json_encode(json_decode($response), JSON_PRETTY_PRINT);
?>

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://secure.agiletelecom.com/services/sms/credit"))
    .header("X-Api-Key", "YOUR_API_KEY")
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

using (var client = new HttpClient()) {
    client.DefaultRequestHeaders.Add("X-Api-Key", "YOUR_API_KEY");
    
    var response = await client.GetAsync("https://secure.agiletelecom.com/services/sms/credit");
    var content = await response.Content.ReadAsStringAsync();
    Console.WriteLine(content);
}

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", 
		"https://secure.agiletelecom.com/services/sms/credit", 
		nil)
	req.Header.Set("X-Api-Key", "YOUR_API_KEY")
	
	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()
	
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

require 'net/https'
require 'json'

uri = URI("https://secure.agiletelecom.com/services/sms/credit")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri.path)
request["X-Api-Key"] = "YOUR_API_KEY"

response = http.request(request)
puts JSON.parse(response.body)

Delivery Notifications

When you enable delivery notifications, AgileTelecom will post the delivery status of each SMS to your webhook endpoint (configured in your account settings). This lets you track whether messages were successfully delivered, rejected, or expired.

Webhook Payload Format

{
  "messageId": "msg-001-20260408",
  "destination": "+393471234567",
  "statusCode": 3,
  "description": "Delivered",
  "doneDate": "2026-04-08 14:35:22.045+0200",
  "concatTotal": 1,
  "concatProgressive": 1,
  "lcrOperator": "22210",
  "realOperator": "22201",
  "price": 0.005
}

Report Fields

Field	Type	Description
messageId	string	Your message ID from the send request
destination	string	Recipient's phone number
statusCode	integer	Status code (see table below)
description	string	Human-readable status (Delivered, Rejected, etc.)
doneDate	string	When the delivery status was determined
concatTotal	integer	Total parts if message was concatenated
concatProgressive	integer	Which part of a concatenated message this is
lcrOperator	string	Network operator code (if available)
realOperator	string	Actual carrier handling the number
price	double	Credit cost for this SMS

Delivery Status Codes

Code	Description	Meaning
1	Accepted	Operator has accepted the message
2	Rejected	Operator rejected the message
3	Delivered	Message successfully delivered to phone
4	Expired	Message was not delivered before expiry
5	Deleted	Message was deleted
6	Undeliverable	Operator unable to deliver

Best Practices

Message Tracking

Always include unique IDs in the ids array when sending messages—this makes webhook delivery reports much easier to match against your records.

Phone Number Format

Use international format with country code. Examples: +39 for Italy, +44 for UK, +1 for USA, +33 for France.

SMS Length Limits

Standard (GSM 7-bit alphabet): 160 characters per part
Unicode (special characters): 70 characters per part
Messages longer than these limits are automatically split into multiple parts (concatenated SMS) if enableConcatenated is true

Sender ID Rules

Alphanumeric: Maximum 11 characters (e.g., "MyCompany", "Support")
Numeric: Maximum 16 digits (e.g., "1234567890123456")
Check error code 26 if your sender ID is rejected

Rate Limits

Contact AgileTelecom support to confirm your account's rate limits (messages per second/minute). Exceeding these limits may result in request queueing or rejection.

Encoding

By default, messages are sent as UTF-8 text. For HEX-encoded bodies, set hexBody: true in your request.

Test with Postman

We provide pre-configured Postman collections to speed up your testing:

Download Collections

How to Import

Open Postman
Click Import (top left corner)
Upload the downloaded JSON file
Confirm the import

Set Your Credentials

In Postman, open the collection in the left sidebar
Navigate to the Variables tab
Update the "Current Value" for:
- username: Your Agile Telecom username (if using Basic Auth)
- password: Your password (if using Basic Auth)
- api-key: Your API key (if using API Key auth)
- enable_apikey: Set to true for API Key, false for Basic Auth
Click Save

Test Data

The collection includes sample requests and placeholder credentials. Replace them with your real credentials before sending actual messages.

Generate Code Snippets

Generate integration code directly from Postman:

Open any request in the collection
Click the </> code icon (right side)
Select your language (cURL, Python, Node.js, PHP, Java, C#, Go, Ruby)
Copy the generated code into your application

Troubleshooting

Error 1 (Wrong credentials): Verify your API key or username/password are correct and enabled in your account.

Error 2 (Insufficient credit): Your account balance is too low. Check credit with the /sms/credit endpoint and top up if needed.

Error 26 (Sender alias not allowed): The sender ID you used is not approved. Configure allowed sender IDs in your account settings.

Error 100 (Source IP not allowed): Your server's IP address is not whitelisted. Update IP whitelist in your account settings.

Need Help?

For technical support or billing questions, reach out to AgileTelecom:

Email: help@agiletelecom.com

Next Steps

Explore related APIs and protocols:

SMS REST API (Universal) - Modern API endpoint with additional features
SMPP Protocol - Binary protocol for high-volume senders
Inbound SMS - Receive and process incoming messages

Base URLs​

Authentication​

Basic Authentication​

API Key (Recommended)​

Send SMS​

Request Body​

Request Parameters​

Message Parameters​

Check Account Credit​

Response Formats​

Success Response (2XX)​

Client Errors (4XX)​

Server Errors (5XX)​

Error Codes​

Code Examples​

Simple SMS​

SMS with Custom Message ID​

Long Message (Concatenated SMS)​

Unicode Message​

Scheduled SMS​

Bulk SMS to Multiple Recipients​

Check Account Credit​

Delivery Notifications​

Webhook Payload Format​

Report Fields​

Delivery Status Codes​

Best Practices​

Test with Postman​

Download Collections​

How to Import​

Set Your Credentials​

Generate Code Snippets​

Troubleshooting​

Need Help?​

Next Steps​

Base URLs

Authentication

Basic Authentication

API Key (Recommended)

Send SMS

Request Body

Request Parameters

Message Parameters

Check Account Credit

Response Formats

Success Response (2XX)

Client Errors (4XX)

Server Errors (5XX)

Error Codes

Code Examples

Simple SMS

SMS with Custom Message ID

Long Message (Concatenated SMS)

Unicode Message

Scheduled SMS

Bulk SMS to Multiple Recipients

Check Account Credit

Delivery Notifications

Webhook Payload Format

Report Fields

Delivery Status Codes

Best Practices

Test with Postman

Download Collections

How to Import

Set Your Credentials

Generate Code Snippets

Troubleshooting

Need Help?

Next Steps