Send an SMS

Send text messages to mobile phones.

Request

POST https://api.46elks.com/a1/sms

Request parameters

Parameter Example Description
from YourCompany

+46700000000
The sender of the SMS as seen by the recipient.

Either a text sender ID or a phone number in E.164 format if you want to be able to receive replies.
to +46700000000 The phone number of the recipient in E.164 format.
message Hello there! The message to send.

Sample code

curl https://api.46elks.com/a1/sms \
    -u <api_username>:<api_password> \
    -d from=CurlyElk \
    -d to=+46700000000 \
    -d message="Bring a sweater, it's cold outside"
  
import HTTPotion.base

authdata = [basic_auth: {'<API-Username>',
                         '<API-Password>'}]

request = %{
  "from"    => "ElixirElk",
  "to"      => "+46700000000",
  "message" => "Bring a sweater, it’s cold outside!"
}

request_data = URI.encode_query(request)

HTTPotion.start
HTTPotion.post("https://api.46elks.com/a1/sms",
  [body: request_data , ibrowse: authdata]
)
  
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

public class UnirestSendSMS {
  public static void main(String[] args) {
    try {
      System.out.println("Sending SMS");

      HttpResponse response = Unirest.post("https://api.46elks.com/a1/sms")
        .basicAuth("<API Username>","<API Password>")
        .field("to", "+46700000000")
        .field("from", "JavaElk")
        .field("message", "Bring a sweater, it’s cold outside!")
        .asString();

      System.out.println(response.getBody());
      }

    catch (Exception e){
        System.out.println(e);
    }
  }
}
  

// API credentials
const username = "< API Username >";
const password = "< API Password >";
const auth  = Buffer.from(username + ":" + password).toString("base64");

let data = {
  from: "NodeElk",
  to: "+46766860001",
  message: "Bring a sweater, it’s cold outside!"
}

data = new URLSearchParams(data);
data = data.toString();

fetch("https://api.46elks.com/a1/sms", {
  method: "post",
  body: data,
  headers: {"Authorization": "Basic "  + auth}
})
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.log(err))
  
function sendSMS ($sms) {
  $username = "USERNAME";
  $password = "PASSWORD";
  $context = stream_context_create(array(
    'http' => array(
      'method' => 'POST',
      'header'  => 'Authorization: Basic '.
                  base64_encode($username.':'.$password). "\r\n".
                  "Content-type: application/x-www-form-urlencoded\r\n",
      'content' => http_build_query($sms,'','&'),
      'timeout' => 10
  )));
  $response = file_get_contents("https://api.46elks.com/a1/sms",
    false, $context);

  if (!strstr($http_response_header[0],"200 OK"))
    return $http_response_header[0];
  return $response;
}
$sms = array(
  "from" => "PHPElk",   /* Can be up to 11 alphanumeric characters */
  "to" => "+46700000000",  /* The mobile number you want to send to */
  "message" => "Bring a sweater, it's cold outside!",
);
echo sendSMS($sms);
  
import requests

response = requests.post(
  'https://api.46elks.com/a1/sms',
  auth = (API_USERNAME, API_PASSWORD),
  data = {
    'from': 'PythonElk',
    'to': '+46700000000',
    'message': "It's cold outside, bring a sweater!"
  }
)
print(response.text)
require 'net/http'

uri = URI('https://api.46elks.com/a1/sms')
req = Net::HTTP::Post.new(uri)
req.basic_auth '<API Username>', '<API Password>'
req.set_form_data(
  :from => 'RubyElk',
  :to => '+46704508449',
  :message => 'Login code 123456'
)

res = Net::HTTP.start(
    uri.host,
    uri.port,
    :use_ssl => uri.scheme == 'https') do |http|
  http.request req
end

puts res.body
  

Optional request parameters

Parameter Example Description
dryrun yes Enable when you want to verify your API request without actually sending an SMS to a mobile phone.

No SMS message will be sent when this is enabled.
whendelivered http://yourapp.example/ping This webhook URL will receive a POST request every time the delivery status changes.
flashsms yes Send the message as a Flash SMS. The message will be displayed immediately upon arrival and not stored.
dontlog message Enable to avoid storing the message text in your history.

The other parameters will still be stored.

Response

Example JSON response
{
  "id": "s70df59406a1b4643b96f3f91e0bfb7b0",
  "from": "YourCompany",
  "to": "+46700000000",
  "parts": 1,
  "message": "This is the message sent to the phone.",
  "created": "2018-07-11T13:37:42.314100",
  "cost": 3500,
  "direction": "outgoing"
}
Attribute Type Description
status string Current delivery status of the message.

Possible values are "created", "sent", "failed" and "delivered".
id string Unique identifier for this SMS.
from string The sender of the SMS as seen by the recipient.

String may start with a letter and contain numbers - Max 11 characters including A-Z, a-z, 0-9.
to string The phone number of the recipient in E.164 format.
message string The message text.
created string Time in UTC when the SMS was created.
delivered string Time in UTC if the SMS has been successfully delivered.
cost integer Cost of sending the SMS. Specified in 10000s of the currency of your account. For an account with currency SEK a cost of 3500 means that the price for sending this SMS was 0.35 SEK.
direction string The direction of the SMS. Set to "outgoing" for sent SMS.
dontlog string Set to "message" if dontlog was enabled.
estimated_cost integer Replaces cost in the response if dryrun was enabled.
parts integer Number of parts the SMS was divided into.

Additional info

Throughput

Default maximum throughput is 100 SMS per minute per account.
Additional messages will be queued and sent in-order.
Contact support if you require additional throughput.

Message texts and cost

SMS messages should always be sent to the API as URL-encoded UTF-8. The maximum text size of a single message is 160 characters. If your message contains characters not available in the GSM 03.38 basic character set it will be encoded as UTF16-BE which as a general rule means up to 70 characters in a single SMS message. You can use \n in a message if you want to get a new line.

Eg. The use of emojis 🦌 in your messages will result in your messages being encoded differently which may increase the number of parts required to send the total message. To ensure you know how many parts your messages will contain you can use the dryrun parameter which will not send your message but instead return a json similar to the one below. You can also use our GSM analyser.

{
    "status": "created",
    "direction": "outgoing",
    "dryrun": "yes",
    "estimated_cost": 7000,
    "flashsms": "no",
    "to": "+46766866966",
    "parts": 2,
    "owner": "u842f2a9cfb50a0f7335f4dec9997f5bc",
    "from": "Elks",
    "message": "This is an example of a response when using
    the dryrun parameter enabled. ☀️"
}

Longer and more expensive SMS messages can be sent. For messages within GSM 03.38 basic, the calculation is N * 153 where N is the number of SMS parts required. For UTF16-BE, the calculation is N * 67 - however, less for code points above 65535.

Splitting and joining multi-part SMS messages are automatically handled by the API. When your message is being split, your account will be charged for each SMS part.

Message status

Created:We've received your request.
Sent:We've sent your message to the recipient
Failed:Unable to deliver your message
Delivered:Message has reached recipient's phone.