Send SMS

Endpoint

Endpoint: POST /v2/batches

Send one or multiple SMS

Request Data Type

At it's core the sending SMS endpoint needs the following values:

{ "sender": "iP1", "recipients":[ "456189040623", "175368927054", "392094880589", "568798567631" ], "body": "A very nice message", }

his will send a text message to each of the recipients containing the message "A very nice message". The sender ID for the message will be "iP1".

sender

The request will be rejected if the sender:

  • Is a number longer than 15 digits
  • Is an alphanumeric sender shorter than 3 characters or longer than 11 characters (Aa-Zz, 0 - 9, 3 - 11 characters)
  • Does not match the regex [0-9A-Za-z]{1,11} or follow the E164 standard

A message may not reach the recipient if:

  • The operator carrying the recipient does not support the sender

recipients

A request will be rejected if a recipients:

  • is longer than 15 characters
  • contains non digit characters

Phone number must be written in MSISDN format. Each phone number is analyzed and validated where the result is displayed as a message status. If this step fails, the message is not sent.

body

A request will be rejected if the body:

  • Is nullempty or only whitespace
  • is longer than 2000 characters

Extended

Some may require additional features such as templating, scheduled sending, delivery reports and setting your own reference.

{ "sender": "iP1", "recipients":{ "456189040623": { "sign": "sent by Bob" }, "175368927054": {}, "392094880589": {}, "568798567631": {} , "default":{ "sign": " sent by iP.1" } }, "body": "A very nice message{sign}", "type": "sms", "datacoding": "gsm", "priority": 1, "deliveryWindows": [ { "opens": "ISO-8601 string", "closes": "ISO-8601 string" }, { "opens": "ISO-8601 string", "closes" : "ISO-8601 string" } ], "deliveryReportUrl": "https://api.example.com/sms/deliveryreport", "reference": "A client reference", "tags": ["marketing", " ux", "design"] }

recipients - templating

In order to utilize our templating system you must convert your previous recipients array to a dictionary of dictionaries. The top level key is the recipient MSISDN (phone number). The second level key is then searched for in the text and then replaced by the second level value.

type

There are two types that an SMS may have sms and flash. sms sms is a regular SMS while flash flash is shown once and then deleted from the handset. Default is sms sms.

datacoding

There are two types that are available:

  • gsm is a 7 bit character set which allows an SMS to be 160 characters long but with a limited range of characters to choose from.
  • ucs is a 2 byte character set which allows all characters(such as emoji, kanji etc) but lowers the character amount to 70 characters per SMS.

If gsm is set any message that requires the extended character set of ucs ucs will be denied from being sent. Default is ucs.

priority

If it is important that your message is delivered quickly and unhindered by others in the message queue, you can set a higher priority for your message. Note that if you set a higher priority, the price per SMS increases by 10 öre if you use a Swedish account, or € 0.01 if you use an international account. Priority 1 is the default value and also the lowest available value, while priority 2 is the highest available value. If priority is set then 1 and 2 are the only allowed values.

deliveryWindows

In case there is a need to schedule a sending in the future there's the possibility to do so with our delivery time windows.

You may have as many windows as you choose. This allows you to send messages at specific times over multiple days eg. every day between 10:00 and 10:05 on business days.

Parsing

  • null in the opens field will be replaced with the current date and time
  • If closes is null the field will be set to 7 days (168 hours) after the opens field. opens

Request will be rejected if windows overlap.

If no windows are given we will create a window which will apply the parsing rule above.

deliveryReportUrl

If provided, status update reports will be sent to this URL through the method POSTThese reports are separate for each message recipient, and each status update. For further reading on these reports see Delivery reports.

reference

This is a property that allows the user to set a custom ID or credential if storing the default generated IDs is deprecated.

Restrictions

  • May be a maximum of 40 characters
  • Can not be empty string or whitespace.

null is default value.

tags

An array of tags used to categorize or sort your bastches. When listing your batches, you can filter by these.

Response

If the request is accepted, the API will return a summary for the batch, which can be found later at the location specified by the location header. For more information about the response data type go to the section "Read Batches". Batches.

We return our response before we've gotten confirmed that your accounts financials has been confirmed so the price summary may not be set.

Code example

Below you will find a simple code example with authentication and functionality for sending an SMS.

Sending SMS C#

using (var client = new HttpClient()) { client.BaseAddress = new Uri("https://api.ip1sms.com/v2/"); client.DefaultRequestHeaders.Accept.Clear(); client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json")); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "API Key"); var sms = new OutgoingSMS() { Sender = "iP1", Recipients = new List () { "46712345678" }, Body = "Test message rest v2", Type = "sms", Datacoding = "gsm", Priority = 1, Reference = "Test", Tags = new List () { "Test SMS" } }; HttpResponseMessage response = await client.PostAsJsonAsync("batches", sms); if (response.IsSuccessStatusCode) { Console.WriteLine("Late"); } else { Console.WriteLine("Failed, " + response.StatusCode + ": " + await response.Content.ReadAsStringAsync()); } } public class OutgoingSMS { public string Sender { get; set; } public List Recipients { get; set; } public string Body { get; set; } public string Type { get; set; } public string DataEncoding { get; set; } public int Priority { get; set; } public string Reference { get; set; } public List Tags { get; set; } }

Sending SMS PHP

$conf = array( 'password' => 'API key', 'apiUrl' => 'api.ip1sms.com/v2/', 'method' => 'POST', 'endpoint' => 'batches', ); $message = array( "sender" => "iP1", "recipients" => ["46712345678"], "body" => "Test message rest v2", "type" => "sms", "datacoding" => "gsm", "priority" => 1, "reference" => "Test", "tags" => ["Test SMS"], ); $jsonEncodedMessage = json_encode($message); // Set up request options $options = array( 'http' => array( 'header' => array( 'Content-Type: application/json', 'Authorization: Bearer '.$conf['password'], 'Content- Length: ' .strlen($jsonEncodedMessage) ), 'method' => $conf['method'], 'content' => $jsonEncodedMessage, ) ); $url = "https://" . $conf['apiUrl'] . $conf['endpoint']; $context = stream_context_create(1TP4Options); // Send the request $response = file_get_contents($url, false, $context); // Print the response echo $response;

Send SMS Visual Basic

Imports System.Net.Http Imports System.Net.Http.Headers Imports System.Net.Http.Json Module Module1 Sub Main() Dim client As New HttpClient() client.BaseAddress = New Uri("https://api.ip1sms .com/v2/") client.DefaultRequestHeaders.Accept.Clear() client.DefaultRequestHeaders.Accept.Add(New MediaTypeWithQualityHeaderValue("application/json")) client.DefaultRequestHeaders.Authorization = New AuthenticationHeaderValue("Bearer", "API Key ") Dim sms As New OutgoingSMS() sms.Sender = "iP1" sms.Recipients = New List(Of String)() From {"46712345678"} sms.Body = "Test message rest v2" sms.Type = "sms " sms.Datacoding = "gsm" sms.Priority = 1 sms.Reference = "Test" sms.Tags = New List(Of String)() From {"Test SMS"} Dim response As HttpResponseMessage = client.PostAsJsonAsync("batches ", sms).Result If response.IsSuccessStatusCode Then Console.WriteLine("Sent") Else Console.WriteLine("Failed, " & response.StatusCode.ToString() & ": " & response.Content.ReadAsStringAsync().Result ) End If End Sub End Module Public Class OutgoingSMS Public Property Sender As String Public Property Recipients As List(Of String) Public Property Body As String Public Property Type As String Public Property Datacoding As String Public Property Priority As Integer Public Property Reference As String Public Property Tags As List(Of String) End Class