Send an SMS

In order to send an SMS, make a POST request to the /sms endpoint.

Request

URL https://api.apitel.co/sms
Method POST
Content type application/x-www-form-urlencoded or application/json

Parameters

to
required
The phone number you are sending the message to. It must be provided in the format:[+][country code][number] For example: +66812345678.
from
The sender the message is from. Either 'ATSMS', or an approved sender name is valid. This parameter is optional. If omitted, your configured default sender name will be used.
ttl
Message Time to live. A value in seconds, between 1 and 21600 (6 hours). If not provided, this value defaults to 21600.
statusCallback
The URL used to deliver status information for the sent message. If provided, it will override the configured status URL for your account.
apiKey
required
Your api key.
apiSecret
required
Your api secret.
text
required

The text of the message encoded as UTF-8.

Messages which contain only ISO-Latin-1 characters can be up to 160 characters in length before being split into messages with a maximum length of 153 characters.

If other characters are used, the text can be up to 70 characters in length before being split into messages with a maximum length of 67 characters.

Each of the resulting messages will be recomposed and displayed as a single message on the recipient's device.

Examples

curl -i -X POST "https://api.apitel.co/sms" \ -H "Content-Type:application/json" \ -d \ '{ "to": "+661234567890", "from": "ATSMS", "text": "A text message", "apiKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "apiSecret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }'
const fetch = require('node-fetch'); const body = { to: '+661234567890', from: 'ATSMS', text: 'A text message', apiKey: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', apiSecret: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' }; fetch('https://api.apitel.co/sms', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) }) .then(res => res.json()) .then(json => console.log(json)) .catch(err => console.error(err));
<?php $data = array( "to" => "+661234567890", "from" => "ATSMS", "text" => "A text message", "apiKey" => "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "apiSecret" => "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" ); $data_string = json_encode($data); $ch = curl_init('https://api.apitel.co/sms'); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST"); curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, array( 'Content-Type: application/json', 'Content-Length: ' . strlen($data_string)) ); $result = curl_exec($ch); $http_code = curl_getinfo( $ch, CURLINFO_HTTP_CODE ); if ( $http_code == "200" ){ echo 'Successful! Server responded with:'.$result; }else{ echo 'Failed! Server responded with:'.$result; } curl_close( $ch ); ?>
require 'net/http' require 'uri' require 'json' uri = URI.parse("https://api.apitel.co/sms") header = {'Content-Type': 'application/json'} body = { to: "+661234567890", from: "ATSMS", text: "A text message", apiKey: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", apiSecret: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } http = Net::HTTP.new(uri.host, uri.port) request = Net::HTTP::Post.new(uri.request_uri, header) request.body = body.to_json response = http.request(request) if response.is_a?(Net::HTTPSuccess) puts "Successful! Server responded with: #{response.body }" else puts "Failed! Server responded with: #{response.body }" end
import requests body = { 'to': "+661234567890", 'from': "ATSMS", 'text': "A text message", 'apiKey': "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", 'apiSecret': "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } r = requests.post('https://api.apitel.co/sms', json=body) if r.status_code >= 200 and r.status_code < 300: print('Successful! Server responded with:', r.json()) else: print('Failed! Server responded with:', r.json())
import org.apache.http.HttpEntity; import org.apache.http.HttpResponse; import org.apache.http.client.HttpClient; import org.apache.http.client.methods.HttpPost; import org.apache.http.entity.StringEntity; import org.apache.http.impl.client.HttpClients; import org.apache.http.util.EntityUtils; import java.io.IOException; // This example requires Apache HTTP Components dependency, // you can access the full documentation for more examples from link below. // http://hc.apache.org/httpcomponents-client-ga // http://hc.apache.org/httpcomponents-client-ga/examples.html public class SendSmsMain { public static void main(String[] args) throws IOException { SendSms(); } public static void SendSms() throws IOException { HttpClient httpclient = HttpClients.createDefault(); HttpPost httppost = new HttpPost("https://api.apitel.co/sms"); String body = "{\"to\":\"+661234567890\"" + ", \"from\":\"ATSMS\"" + ",\"text\":\"A text message\"" + ",\"apiKey\":\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"" + ",\"apiSecret\":\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"}"; httppost.setEntity(new StringEntity(body, "UTF-8")); httppost.addHeader("Content-Type", "application/json"); HttpResponse response = httpclient.execute(httppost); HttpEntity entity = response.getEntity(); String responseBody = entity != null ? EntityUtils.toString(entity) : null; int status = response.getStatusLine().getStatusCode(); if (status >= 200 && status < 300) { System.out.println("Successful! Server responded with:" + responseBody); } else { System.out.println("Failed! Server responded with:" + responseBody); } } }
using System; using System.Net.Http; using System.Text; using System.Threading.Tasks; namespace apitel_test { class Program { static void Main(string[] args) { SendSmsAsync().Wait(); } private static async Task SendSmsAsync() { using (HttpClient client = new HttpClient()) { var url = "https://api.apitel.co/sms"; var body = "{\"to\":\"+661234567890\"" + ", \"from\":\"ATSMS\"" + ",\"text\":\"A text message\"" + ",\"apiKey\":\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"" + ",\"apiSecret\":\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"}"; var payload = new StringContent(body, Encoding.UTF8, "application/json"); var response = await client.PostAsync(url, payload); using (HttpContent content = response.Content) { string result = await content.ReadAsStringAsync(); if (response.StatusCode == System.Net.HttpStatusCode.OK) { Console.WriteLine("Successful! Server responded with:" + result); } else { Console.WriteLine("Failed! Server responded with:" + result); } } } } } }

Response

Request responses are formatted as JSON. When a request is successful an HTTP 200 response will be returned. If there is an error with the request an HTTP 400 response will be returned.

Keys

id
The message ID.
to
The phone number the message was sent to.
from
The sender ID the message is from.
text
The text of the message.
status
The status of the message.
errors
Request errors grouped by parameter.
segments
If the length of the message text resulted in multiple messages being sent the message id, and text of each message will be available as an array of objects with id and text keys.
creditRemaining
The amount of credit remaining in your account at the time this message was accepted.

Examples

A successful response.

{ "id": 13, "from": "ATSMS", "to": "+661234567890", "text": "Good evening.", "status": "ACCEPTED" }

A successful response when sending a long message. While two messages are sent, only one message will be displayed on the recipeint's device.

{ "id": 91, "from": "ATSMS", "to": "+661234567890", "text": "Good evening. There is a lot to say in this message. I suspect it may be too long to fit in a single sms. Unfortunately, they're limited in length to only 140 bytes.", "status": "ACCEPTED", "segments":[ { "id": 91, "text": "Good evening. There is a lot to say in this message. I suspect it may be too long to fit in a single sms. Unfortunately, they're limited in length to onl" }, { "id": 92, "text": "y 140 bytes." } ] }

A response to an unparseable request. This may happen if the incorrect content type is specified, or there is a syntax error in the parameter encoding.

{ "errors": { "request": [ "Unable to parse request" ] } }

A response to a request with missing parameters. In this example the from parameter was not provided.

{ "errors": { "from": [ "can't be empty" ] } }

SMS status

In order to recieve status details about sent messages you'll need to implement a status webhook. You will then need to configure your account to send status notifications to this URL. For example: http://yourdomain.com/sms-status.

An example webhook implementation.

const express = require('express') const app = express() app.route('/sms-status').get(function(request, response) { handleStatus(request.query, response) }); function handleStatus(query, response) { console.log('message id', query.id); console.log('message status', query.status); response.sendStatus(200) } app.listen(8080);
<?php $id = $_GET['id']; $status = $_GET['status']; $text = "message id: " . $id . " message status: " . $status; // change this to a file which the php process can write to $file = "/path/to/status_log.txt"; file_put_contents($file, $text, FILE_APPEND | LOCK_EX); http_response_code(200); ?>
# http://sinatrarb.com/ require 'sinatra' get '/' do id = params["id"] status = params["status"] puts "message id: #{id}" puts "message status: #{status}" [200, ""] end
from flask import Flask, request, make_response app = Flask(__name__) @app.route("/", methods=['GET']) def sms_status(): id = request.args.get('id') status = request.args.get('status') print('message id:', id) print('message status:', status) return make_response("", 200)
// http://sparkjava.com/ import static spark.Spark.*; public class SMSStatus { public static void main(String[] args) { port(8080); get("/", (request, response) -> { String id = request.queryParams("id"); String status = request.queryParams("status"); System.out.println("message id: "+ id); System.out.println("message status: "+ status); response.status(200); return ""; }); } }
// http://nancyfx.org/ namespace NancyTemplate { using Nancy; using System; public class HomeModule : NancyModule { public HomeModule() { Get("/", parameters => { var id = Request.Query.id; var status = Request.Query.status; Console.WriteLine("message id: "+ id); Console.WriteLine("message status: "+ status); return HttpStatusCode.OK; }); } } }

The status webhook request will contain the message id in the 'id' parameter, and the message status in the 'status' parameter. For example: http://yourdomain.com/sms-status?id=1&status=DELIVERED

Status values

ACCEPTED
The message is valid, and will be sent.
SENT
The message has been sent. Waiting for delivery receipt.
DELIVERED
The message has been delivered.
SEND_ERROR
An error occured while sending the message.
DELIVERY_ERROR
The message has been sent but it can't reach to the receiver

In the case that a message is not delivered, a reason will be displayed on your dashboard . Descriptions of these reasons are provided below.

Undelivered status

Undelivered
A general error, for which we don't have any additional information.
Unreachable
The handset was either out of range of the network, was turned off, had a dead battery, or otherwise was unable to be contacted.
Expired
The message was unable to be routed through the network within the time limit.
SIM card full
The SIM card of the handset is full.
Unroutable
A route to the appropriate network can't be found. This usually means it can't be determined which network currently controls the phone number.

In the case of 'Expired' messages, resending the message may result in it being succesfully delivered. In the case of the other error types, resending the message most likely won't be successful.

Send SMS Batch

In order to send multiple SMS as a batch, make a POST request to the /sms-batch endpoint.

Request

URL https://api.apitel.co/sms-batch
Method POST
Content type application/json

Parameters

from
The default sender id that will be used for all messages in the batch. If absent, the default sender id for the users account will be used.
statusCallback
The URL used to deliver status information for the sent messages. If provided, it will override the configured status URL for your account.
messages
required

An array of message objects. A batch can contain a maximum of 10000 messages.

apiKey
required
Your api key.
apiSecret
required
Your api secret.
name

The batch name, it can contain a maximum of 20 characters.

Message object

to
required
The phone number to send the message to.
from
The sender name to be used for this message. If absent, the value of the parent `from` key will be used.
text
required

The text of the message encoded as UTF-8.

Messages which contain only ISO-Latin-1 characters can be up to 160 characters in length before being split into messages with a maximum length of 153 characters.

If other characters are used, the text can be up to 70 characters in length before being split into messages with a maximum length of 67 characters.

Each of the resulting messages will be recomposed and displayed as a single message on the recipient's device.

Examples

curl -i -X POST "https://api.apitel.co/sms-batch" \ -H "Content-Type:application/json" \ -d \ '{ "from":"ATSMS", "apiKey":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "apiSecret":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "messages":[ {"to":"+661234567890","text":"A first text message"}, {"to":"+661234567891","text":"A second text message"} ] }'
const fetch = require('node-fetch'); const body = { from: 'ATSMS', apiKey: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', apiSecret: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', messages: [{ to: '+661234567890', text: 'A first text message' }, { to: '+661234567891', text: 'A second text message' } ] } fetch('https://api.apitel.co/sms-batch', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) }) .then(res => res.json()) .then(json => console.log(json)) .catch(err => console.error(err));
<?php $data = array( "from" => "ATSMS", "apiKey" => "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "apiSecret" => "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "message" => array( array("to" => "+661234567890", "text" => "A first text message"), array("to" => "+661234567891", "text" => "A second text message"), ) ); $data_string = json_encode($data); $ch = curl_init('https://api.apitel.co/sms-batch'); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST"); curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, array( 'Content-Type: application/json', 'Content-Length: ' . strlen($data_string)) ); $result = curl_exec($ch); $http_code = curl_getinfo( $ch, CURLINFO_HTTP_CODE ); if ( $http_code == "200" ){ echo 'Successful! Server responded with:'.$result; }else{ echo 'Failed! Server responded with:'.$result; } curl_close( $ch ); ?>
require 'net/http' require 'uri' require 'json' uri = URI.parse("https://api.apitel.co/sms-batch") header = {'Content-Type': 'application/json'} body = { from: 'ATSMS', apiKey: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', apiSecret: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', messages: [{ to: '+661234567890', text: 'A first text message' }, { to: '+661234567891', text: 'A second text message' } ] } http = Net::HTTP.new(uri.host, uri.port) request = Net::HTTP::Post.new(uri.request_uri, header) request.body = body.to_json response = http.request(request) if response.is_a?(Net::HTTPSuccess) puts "Successful! Server responded with: #{response.body }" else puts "Failed! Server responded with: #{response.body }" end
import requests body = { 'from': "ATSMS", 'apiKey': "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", 'apiSecret': "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", 'messages': [ {'to': "+661234567890",'text': "A first text message"}, {'to': "+661234567891",'text': "A second text message"} ] } r = requests.post('https://api.apitel.co/sms-batch', json=body) if r.status_code >= 200 and r.status_code < 300: print('Successful! Server responded with:', r.json()) else: print('Failed! Server responded with:', r.json())
import org.apache.http.HttpEntity; import org.apache.http.HttpResponse; import org.apache.http.client.HttpClient; import org.apache.http.client.methods.HttpPost; import org.apache.http.entity.StringEntity; import org.apache.http.impl.client.HttpClients; import org.apache.http.util.EntityUtils; import java.io.IOException; // This example requires Apache HTTP Components dependency, // you can access the full documentation for more examples from link below. // http://hc.apache.org/httpcomponents-client-ga // http://hc.apache.org/httpcomponents-client-ga/examples.html public class SendSmsMain { public static void main(String[] args) throws IOException { SendSms(); } public static void SendSms() throws IOException { HttpClient httpclient = HttpClients.createDefault(); HttpPost httppost = new HttpPost("https://api.apitel.co/sms-batch"); String body = "{\"from\":\"ATSMS\"" + ", \"apiKey\":\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"" + ", \"apiSecret\":\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"" + ",\"messages\":[" + "{\"to\":\"+661234567890\", \"text\":\"A first text message\"},"+ "{\"to\":\"+661234567891\", \"text\":\"A second text message\"}"+ "]}"; httppost.setEntity(new StringEntity(body, "UTF-8")); httppost.addHeader("Content-Type", "application/json"); HttpResponse response = httpclient.execute(httppost); HttpEntity entity = response.getEntity(); String responseBody = entity != null ? EntityUtils.toString(entity) : null; int status = response.getStatusLine().getStatusCode(); if (status >= 200 && status < 300) { System.out.println("Successful! Server responded with:" + responseBody); } else { System.out.println("Failed! Server responded with:" + responseBody); } } }
using System; using System.Net.Http; using System.Text; using System.Threading.Tasks; namespace apitel_test { class Program { static void Main(string[] args) { SendSmsAsync().Wait(); } private static async Task SendSmsAsync() { using (HttpClient client = new HttpClient()) { var url = "https://api.apitel.co/sms-batch"; var body = "{\"from\":\"ATSMS\"" + ", \"apiKey\":\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"" + ", \"apiSecret\":\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"" + ",\"messages\":[" + "{\"to\":\"+661234567890\", \"text\":\"A first text message\"},"+ "{\"to\":\"+661234567891\", \"text\":\"A second text message\"}"+ "]}"; var payload = new StringContent(body, Encoding.UTF8, "application/json"); var response = await client.PostAsync(url, payload); using (HttpContent content = response.Content) { string result = await content.ReadAsStringAsync(); if (response.StatusCode == System.Net.HttpStatusCode.OK) { Console.WriteLine("Successful! Server responded with:" + result); } else { Console.WriteLine("Failed! Server responded with:" + result); } } } } } }

Response

Request responses are formatted as JSON. When a request is successful an HTTP 200 response will be returned. If there is an error with the request an HTTP 400 response will be returned.

Keys

id
The batch id
name

The batch name

totalCount
The total count of messages in the batch
acceptedCount
The total count of valid messages in the batch
rejectedCount
The total count of invalid messages in the batch
errors
In the case of a successful request, the errors key will contain an array of errors representing each invalid message. If the request was not successful, the errors key will contain information for each key in error.

Examples

A successful response.

{ "id": 106, "name": "batch#1", "totalCount": 2, "acceptedCount": 2, "rejectedCount": 0 }

A response to an unparseable request. This may happen if the incorrect content type is specified, or there is a syntax error in the parameter encoding.

{ "errors": { "request": [ "Unable to parse request" ] } }

A response to a request with missing parameters. In this example the messages parameter was not provided.

{ "errors": { "messages": "can't be empty." } }

A response to a partial successful request. The errors will contain information of each invalid message

{ "id": 11, "name": "batch#1", "totalCount": 2, "acceptedCount": 1, "rejectedCount": 1, "errors": [{ "index": 1, "text": "can't be empty" }] }

Batch SMS Status

Status of messages sent in a batch will be provided via the status webhook . Each message will include the associated batch_id.

SMS Batch Info

In order to retrieve information about a batch of SMS, make a GET request to the /sms-batch/{id} endpoint.

Request

URL https://api.apitel.co/sms-batch/{id}
Method GET

Parameters

id
required
The batch id
apiKey
required
Your api key.
apiSecret
required
Your api secret.

Examples

curl -X GET 'https://api.apitel.co/sms-batch/127?apiKey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&apiSecret=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
const fetch = require('node-fetch'); const { URL } = require('url'); const url = new URL(`https://api.apitel.co/sms-batch/127`); url.searchParams.append("apiKey", "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"); url.searchParams.append("apiSecret", "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"); fetch(url.href, { method: 'GET', headers: { 'Content-Type': 'application/json' } }) .then(res => res.json()) .then(json => console.log(json)) .catch(err => console.error(err));
<?php $qs = '?apiKey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' .'&apiSecret=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'; $ch = curl_init('https://api.apitel.co/sms-batch/127'.$qs); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $result = curl_exec($ch); $http_code = curl_getinfo( $ch, CURLINFO_HTTP_CODE ); if ( $http_code == "200" ){ echo 'Successful! Server responded with:'.$result; }else{ echo 'Failed! Server responded with:'.$result; } curl_close( $ch ); ?>
require 'net/http' require 'uri' require 'json' url = "https://api.apitel.co/sms-batch/127" qs = "?apiKey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" qs += "&apiSecret=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" uri = URI.parse("#{url}#{qs}") http = Net::HTTP.new(uri.host, uri.port) request = Net::HTTP::Get.new(uri.request_uri) response = http.request(request) if response.is_a?(Net::HTTPSuccess) puts "Successful! Server responded with: #{response.body }" else puts "Failed! Server responded with: #{response.body }" end
import requests params = { 'apiKey': "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", 'apiSecret': "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } r = requests.get('https://api.apitel.co/sms-batch/127', params = params) if r.status_code >= 200 and r.status_code < 300: print('Successful! Server responded with:', r.json()) else: print('Failed! Server responded with:', r.json())
import org.apache.http.HttpEntity; import org.apache.http.HttpResponse; import org.apache.http.client.HttpClient; import org.apache.http.client.methods.HttpGet; import org.apache.http.client.utils.URIBuilder; import org.apache.http.impl.client.HttpClients; import org.apache.http.util.EntityUtils; import java.io.IOException; import java.net.URI; import java.net.URISyntaxException; // This example requires Apache HTTP Components dependency, // you can access the full documentation for more examples from link below. // http://hc.apache.org/httpcomponents-client-ga // http://hc.apache.org/httpcomponents-client-ga/examples.html public class ListSenderNameMain { public static void main(String[] args) throws IOException, URISyntaxException { ListSenderName(); } public static void ListSenderName() throws IOException, URISyntaxException { HttpClient httpclient = HttpClients.createDefault(); URI uri = new URIBuilder() .setScheme("https") .setHost("api.apitel.co") .setPath("/sms-batch/127") .setParameter("apiKey", "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx") .setParameter("apiSecret", "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx") .build(); HttpGet httpget = new HttpGet(uri); HttpResponse response = httpclient.execute(httpget); HttpEntity entity = response.getEntity(); String responseBody = entity != null ? EntityUtils.toString(entity) : null; int status = response.getStatusLine().getStatusCode(); if (status >= 200 && status < 300) { System.out.println("Successful! Server responded with:" + responseBody); } else { System.out.println("Failed! Server responded with:" + responseBody); } } }
using System; using System.Net.Http; using System.Text; using System.Threading.Tasks; namespace apitel_test { class Program { static void Main(string[] args) { ListSenderNameAsync().Wait(); } private static async Task ListSenderNameAsync() { using (HttpClient client = new HttpClient()) { var url = "https://api.apitel.co/sms-batch/127"; var qs = "?apiKey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"; qs += "&apiSecret=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"; var response = await client.GetAsync(url + qs); using (HttpContent content = response.Content) { string result = await content.ReadAsStringAsync(); if (response.StatusCode == System.Net.HttpStatusCode.OK) { Console.WriteLine("Successful! Server responded with:" + result); } else { Console.WriteLine("Failed! Server responded with:" + result); } } } } } }

Response

Request responses are formatted as JSON. When a request is successful an HTTP 200 response will be returned. If there is an error with the request an HTTP 400 response will be returned.

Keys

id
The batch id.
name
The batch name
totalCount
The total count of messages in the batch.
acceptedCount
The total count of valid messages in the batch.
rejectedCount
The total count of invalid messages in the batch.
sentCount
The total count of sent messages in the batch.
deliveredCount
The total count of delivered messages in the batch.
undeliveredCount
The total count of undelivered messages in the batch.
messages
An array of message objects. A batch can contain a maximum of 10000 messages.
isActive
True until all messages are determined to either be delivered or undelivered.

Message object

id
The message ID.
from
The sender ID the message is from.
to
The phone number the message was sent to.
status
The status of the message.

Examples

A successful response

{ "id": 127, "name": "batch#2", "totalCount": 3, "acceptedCount": 3, "rejectedCount": 0, "sentCount": 0, "deliveredCount": 0, "undeliveredCount": 0, "messages": [{ "id": 16987909, "from": "ATSMS", "to": "+661234567890", "state": "DELIVERED" }, { "id": 16987910, "from": "ATSMS", "to": "+661234567891", "state": "DELIVERED" }, { "id": 16987911, "from": "ATSMS", "to": "+661234567892", "state": "DELIVERED" } ], "isActive": true }

Sender names

The sender names API supports requesting, and deleting a sender name, as well as listing your sender names.

Request sender name

In order to request a sender name, make a POST request to the /sender_names endpoint.

Request

URL https://api.apitel.co/sender_names
Method POST
Content type application/x-www-form-urlencoded or application/json

Parameters

name
required
The name you are requesting. It must be no longer than 11 characters, and only contain letters and numbers.
purpose
required
What the sender name will be used for. It must be one of: OTP, NOTIFICATION or MARKETING.
ownerType
required
One of COMPANY, NAME or WEBSITE
owner
required
The company name, individual name, or website who is registering the sender name. Use the value which is specified in ownerType
exampleMsg
required
An example of the messages that will be sent using this sender name. eg Your OTP is 123456 (Ref. ABCD) 18:00.
apiKey
required
Your api key.
apiSecret
required
Your api secret.

Examples

curl -i -X POST https://api.apitel.co/sender_names \ -H "Content-Type:application/json" \ -d \ '{ "name": "goodco", "purpose": "NOTIFICATION", "exampleMsg": "Your OTP is 123456 (Ref. ABCD) 18:00", "ownerType": "WEBSITE", "owner": "http://apitel.co", "apiKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "apiSecret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }'
const fetch = require('node-fetch'); const body = { name: "goodco", purpose: "NOTIFICATION", exampleMsg: "Your OTP is 123456 (Ref. ABCD) 18:00", ownerType: "WEBSITE", owner: "http://apitel.co", apiKey: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", apiSecret: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }; fetch('https://api.apitel.co/sender_names', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) }) .then(res => res.json()) .then(json => console.log(json)) .catch(err => console.error(err));
<?php $data = array( "name" => "goodco", "purpose" => "NOTIFICATION", "exampleMsg" => "Your OTP is 123456 (Ref. ABCD) 18:00", "ownerType" => "WEBSITE", "owner" => "http://apitel.co", "apiKey" => "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "apiSecret" => "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" ); $data_string = json_encode($data); $ch = curl_init('https://api.apitel.co/sender_names'); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST"); curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, array( 'Content-Type: application/json', 'Content-Length: ' . strlen($data_string)) ); $result = curl_exec($ch); $http_code = curl_getinfo( $ch, CURLINFO_HTTP_CODE ); if ( $http_code == "200" ){ echo 'Successful! Server responded with:'.$result; }else{ echo 'Failed! Server responded with:'.$result; } curl_close( $ch ); ?>
require 'net/http' require 'uri' require 'json' uri = URI.parse("https://api.apitel.co/sender_names") header = {'Content-Type': 'application/json'} body = { name: "goodco", purpose: "NOTIFICATION", exampleMsg: "Your OTP is 123456 (Ref. ABCD) 18:00", ownerType: "WEBSITE", owner: "http://apitel.co", apiKey: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", apiSecret: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } http = Net::HTTP.new(uri.host, uri.port) request = Net::HTTP::Post.new(uri.request_uri, header) request.body = body.to_json response = http.request(request) if response.is_a?(Net::HTTPSuccess) puts "Successful! Server responded with: #{response.body }" else puts "Failed! Server responded with: #{response.body }" end
import requests body = { 'name': "goodco", 'purpose': "NOTIFICATION", 'exampleMsg': "Your OTP is 123456 (Ref. ABCD) 18:00", 'ownerType': "WEBSITE", 'owner': "http://apitel.co", 'apiKey': "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", 'apiSecret': "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } r = requests.post('https://api.apitel.co/sender_names', json=body) if r.status_code >= 200 and r.status_code < 300: print('Successful! Server responded with:', r.json()) else: print('Failed! Server responded with:', r.json())
import org.apache.http.HttpEntity; import org.apache.http.HttpResponse; import org.apache.http.client.HttpClient; import org.apache.http.client.methods.HttpPost; import org.apache.http.entity.StringEntity; import org.apache.http.impl.client.HttpClients; import org.apache.http.util.EntityUtils; import java.io.IOException; // This example requires Apache HTTP Components dependency, // you can access the full documentation for more examples from link below. // http://hc.apache.org/httpcomponents-client-ga // http://hc.apache.org/httpcomponents-client-ga/examples.html public class RequestSenderNameMain { public static void main(String[] args) throws IOException { RequestSenderName(); } public static void RequestSenderName() throws IOException { HttpClient httpclient = HttpClients.createDefault(); HttpPost httppost = new HttpPost("https://api.apitel.co/sender_names"); String body = "{\"name\":\"goodco\"" + ",\"purpose\":\"NOTIFICATION\"" + ",\"exampleMsg\":\"Your OTP is 123456 (Ref. ABCD) 18:00\"" + ",\"ownerType\":\"WEBSITE\"" + ",\"owner\":\"http://apitel.co\"" + ",\"apiKey\":\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"\"" + ",\"apiSecret\":\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"\"}"; httppost.setEntity(new StringEntity(body, "UTF-8")); httppost.addHeader("Content-Type", "application/json"); HttpResponse response = httpclient.execute(httppost); HttpEntity entity = response.getEntity(); String responseBody = entity != null ? EntityUtils.toString(entity) : null; int status = response.getStatusLine().getStatusCode(); if (status >= 200 && status < 300) { System.out.println("Successful! Server responded with:" + responseBody); } else { System.out.println("Failed! Server responded with:" + responseBody); } } }
using System; using System.Net.Http; using System.Text; using System.Threading.Tasks; namespace apitel_test { class Program { static void Main(string[] args) { RequestSenderNameAsync().Wait(); } private static async Task RequestSenderNameAsync() { using (HttpClient client = new HttpClient()) { var url = "https://api.apitel.co/sender_names"; var body = "{\"name\":\"goodco\"" + ",\"purpose\":\"NOTIFICATION\"" + ",\"exampleMsg\":\"Your OTP is 123456 (Ref. ABCD) 18:00\"" + ",\"ownerType\":\"WEBSITE\"" + ",\"owner\":\"http://apitel.co\"" + ",\"apiKey\":\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"" + ",\"apiSecret\":\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"}"; var payload = new StringContent(body, Encoding.UTF8, "application/json"); var response = await client.PostAsync(url, payload); using (HttpContent content = response.Content) { string result = await content.ReadAsStringAsync(); if (response.StatusCode == System.Net.HttpStatusCode.OK) { Console.WriteLine("Successful! Server responded with:" + result); } else { Console.WriteLine("Failed! Server responded with:" + result); } } } } } }

Response

Request responses are formatted as JSON. When a request is successful an HTTP 200 response will be returned. If there is an error with the request an HTTP 400 response will be returned.

Keys

name
The sender name requested.
pending
Either true of false. Reflects if the sender name is pending approval. Once approved, pending will be false. Rejected sender names will be removed.
reliable
Either true of false. Reflects if the sender name is reliable, or not. Messages sent from an unreliable sender name will more often be blocked as spam.
default
Either true of false. Reflects if the sender name is the default sender name for your account.

Examples

A successful response

{ "name": "goodco", "pending": true, "reliable": false, "default": false }

List sender names

In order to list your sender names, make a GET request to the /sender_names endpoint.

Request

URL https://api.apitel.co/sender_names
Method GET

Parameters

apiKey
required
Your api key.
apiSecret
required
Your api secret.

Examples

curl -X GET 'https://api.apitel.co/sender_names?apiKey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&apiSecret=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
const fetch = require('node-fetch'); const { URL } = require('url'); const url = new URL(`https://api.apitel.co/sender_names`); url.searchParams.append("apiKey", "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"); url.searchParams.append("apiSecret", "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"); fetch(url.href, { method: 'GET', headers: { 'Content-Type': 'application/json' } }) .then(res => res.json()) .then(json => console.log(json)) .catch(err => console.error(err));
<?php $qs = '?apiKey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' .'&apiSecret=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'; $ch = curl_init('https://api.apitel.co/sender_names'.$qs); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $result = curl_exec($ch); $http_code = curl_getinfo( $ch, CURLINFO_HTTP_CODE ); if ( $http_code == "200" ){ echo 'Successful! Server responded with:'.$result; }else{ echo 'Failed! Server responded with:'.$result; } curl_close( $ch ); ?>
require 'net/http' require 'uri' require 'json' url = "https://api.apitel.co/sender_names" qs = "?apiKey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" qs += "&apiSecret=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" uri = URI.parse("#{url}#{qs}") http = Net::HTTP.new(uri.host, uri.port) request = Net::HTTP::Get.new(uri.request_uri) response = http.request(request) if response.is_a?(Net::HTTPSuccess) puts "Successful! Server responded with: #{response.body }" else puts "Failed! Server responded with: #{response.body }" end
import requests params = { 'apiKey': "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", 'apiSecret': "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } r = requests.get('https://api.apitel.co/sender_names', params = params) if r.status_code >= 200 and r.status_code < 300: print('Successful! Server responded with:', r.json()) else: print('Failed! Server responded with:', r.json())
import org.apache.http.HttpEntity; import org.apache.http.HttpResponse; import org.apache.http.client.HttpClient; import org.apache.http.client.methods.HttpGet; import org.apache.http.client.utils.URIBuilder; import org.apache.http.impl.client.HttpClients; import org.apache.http.util.EntityUtils; import java.io.IOException; import java.net.URI; import java.net.URISyntaxException; // This example requires Apache HTTP Components dependency, // you can access the full documentation for more examples from link below. // http://hc.apache.org/httpcomponents-client-ga // http://hc.apache.org/httpcomponents-client-ga/examples.html public class ListSenderNameMain { public static void main(String[] args) throws IOException, URISyntaxException { ListSenderName(); } public static void ListSenderName() throws IOException, URISyntaxException { HttpClient httpclient = HttpClients.createDefault(); URI uri = new URIBuilder() .setScheme("https") .setHost("api.apitel.co") .setPath("/sender_names") .setParameter("apiKey", "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx") .setParameter("apiSecret", "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx") .build(); HttpGet httpget = new HttpGet(uri); HttpResponse response = httpclient.execute(httpget); HttpEntity entity = response.getEntity(); String responseBody = entity != null ? EntityUtils.toString(entity) : null; int status = response.getStatusLine().getStatusCode(); if (status >= 200 && status < 300) { System.out.println("Successful! Server responded with:" + responseBody); } else { System.out.println("Failed! Server responded with:" + responseBody); } } }
using System; using System.Net.Http; using System.Text; using System.Threading.Tasks; namespace apitel_test { class Program { static void Main(string[] args) { ListSenderNameAsync().Wait(); } private static async Task ListSenderNameAsync() { using (HttpClient client = new HttpClient()) { var url = "https://api.apitel.co/sender_names"; var qs = "?apiKey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"; qs += "&apiSecret=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"; var response = await client.GetAsync(url + qs); using (HttpContent content = response.Content) { string result = await content.ReadAsStringAsync(); if (response.StatusCode == System.Net.HttpStatusCode.OK) { Console.WriteLine("Successful! Server responded with:" + result); } else { Console.WriteLine("Failed! Server responded with:" + result); } } } } } }

Response

Request responses are formatted as JSON. The body will be an array of sender name objects. Each of the objects will have the following keys.

Keys

name
The sender name.
pending
Either true of false. Reflects if the sender name is pending approval.
reliable
Either true of false. Reflects if the sender name is reliable, or not. Messages sent from an unreliable sender name will more often be blocked as spam.
default
Either true of false. Reflects if the sender name is the default sender name for your account.

Examples

A successful response

{ "sender_names": [ { "name": "goodco", "pending": true, "reliable": false, "default": false }, { "name": "verygoodco", "pending": false, "reliable": true, "default": true } ] }

Delete sender name

In order to delete a sender name, make a DELTE request to the /sender_names/{name} endpoint.

Request

URL https://api.apitel.co/sender_names/{name}
Method DELETE

Parameters

apiKey
required
Your api key.
apiSecret
required
Your api secret.

Examples

curl -X DELETE 'https://api.apitel.co/sender_names/goodco?apiKey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&apiSecret=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
const fetch = require('node-fetch'); const { URL } = require('url'); const sender_name = 'goodco'; const url = new URL(`https://api.apitel.co/sender_names/${sender_name}`); url.searchParams.append("apiKey", "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"); url.searchParams.append("apiSecret", "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"); fetch(url.href, { method: 'DELETE', headers: { 'Content-Type': 'application/json' } }) .then(res => res.json()) .then(json => console.log(json)) .catch(err => console.error(err));
<?php $sender_name = 'goodco'; $qs = '?apiKey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' .'&apiSecret=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'; $ch = curl_init('https://api.apitel.co/sender_names/'.$sender_name.$qs); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $result = curl_exec($ch); $http_code = curl_getinfo( $ch, CURLINFO_HTTP_CODE ); if ( $http_code == "200" ){ echo 'Successful! Server responded with:'.$result; }else{ echo 'Failed! Server responded with:'.$result; } curl_close( $ch ); ?>
require 'net/http' require 'uri' url = "https://api.apitel.co/sender_names" sender_name = "goodco" qs = "?apiKey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" qs += "&apiSecret=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" uri = URI.parse("#{url}/#{sender_name}#{qs}") http = Net::HTTP.new(uri.host, uri.port) request = Net::HTTP::Delete.new(uri.request_uri) response = http.request(request) if response.is_a?(Net::HTTPSuccess) puts "Successful! Server responded with: #{response.body }" else puts "Failed! Server responded with: #{response.body }" end
import requests params = { 'apiKey': "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", 'apiSecret': "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } r = requests.delete('https://api.apitel.co/sender_names/goodco', params = params) if r.status_code >= 200 and r.status_code < 300: print('Successful! Server responded with:', r.json()) else: print('Failed! Server responded with:', r.json())
import org.apache.http.HttpEntity; import org.apache.http.HttpResponse; import org.apache.http.client.HttpClient; import org.apache.http.client.methods.HttpDelete; import org.apache.http.client.utils.URIBuilder; import org.apache.http.impl.client.HttpClients; import org.apache.http.util.EntityUtils; import java.io.IOException; import java.net.URI; import java.net.URISyntaxException; // This example requires Apache HTTP Components dependency, // you can access the full documentation for more examples from link below. // http://hc.apache.org/httpcomponents-client-ga // http://hc.apache.org/httpcomponents-client-ga/examples.html public class DelSenderNameMain { public static void main(String[] args) throws IOException, URISyntaxException { DelSenderName(); } public static void DelSenderName() throws IOException, URISyntaxException { HttpClient httpclient = HttpClients.createDefault(); URI uri = new URIBuilder() .setScheme("https") .setHost("api.apitel.co") .setPath("/sender_names/goodco") .setParameter("apiKey", "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx") .setParameter("apiSecret", "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx") .build(); HttpDelete httpdelete = new HttpDelete(uri); HttpResponse response = httpclient.execute(httpdelete); HttpEntity entity = response.getEntity(); String responseBody = entity != null ? EntityUtils.toString(entity) : null; int status = response.getStatusLine().getStatusCode(); if (status >= 200 && status < 300) { System.out.println("Successful! Server responded with:" + responseBody); } else { System.out.println("Failed! Server responded with:" + responseBody); } } }
using System; using System.Net.Http; using System.Text; using System.Threading.Tasks; namespace apitel_test { class Program { static void Main(string[] args) { DelSenderNameAsync().Wait(); } private static async Task DelSenderNameAsync() { using (HttpClient client = new HttpClient()) { var url = "https://api.apitel.co/sender_names/goodco"; var qs = "?apiKey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"; qs += "&apiSecret=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"; var response = await client.DeleteAsync(url + qs); using (HttpContent content = response.Content) { string result = await content.ReadAsStringAsync(); if (response.StatusCode == System.Net.HttpStatusCode.OK) { Console.WriteLine("Successful! Server responded with:" + result); } else { Console.WriteLine("Failed! Server responded with:" + result); } } } } } }

Response

Request responses are formatted as JSON. The body will be the deleted sender name.

Keys

name
The sender name.
pending
Either true of false. Reflects if the sender name is pending approval.
reliable
Either true of false. Reflects if the sender name is reliable, or not. Messages sent from an unreliable sender name will more often be blocked as spam.
default
Either true of false. Reflects if the sender name is the default sender name for your account.

Examples

A successful response.

{ "name": "goodco", "pending": false, "reliable": false, "default": false }