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",
}

Dessa värden kommer att direkt att skicka ett meddelande till varje mottagare med meddelande-texten “A very nice message”. Avsändaren på meddelandet kommer att vara “Testnos”

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

Each phone number will then be parsed and validated where the result will appear as a status for the message. If this step fails the message will not be 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

In case it it very important for you that your messages to arrive quickly and not be hindered by by our other customers you may set a higher priority. However setting the priority to a higher value will increase the price by 0.01 EUR. Priority 1 is the default and is the lowest priority that is available, and Priority 2 is the highest priority available. If provided then 1 and 2 are the only valid 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 on 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<string>() { "46712345678" },
        Body = "Test message rest v2",
        Type = "sms",
        Datacoding = "gsm",
        Priority = 1,
        Reference = "Test",
        Tags = new List<string>() { "Test SMS" }
    };

    HttpResponseMessage response = await client.PostAsJsonAsync("batches", sms);

    if (response.IsSuccessStatusCode)
    {
        Console.WriteLine("Sent");
    }
    else
    {
        Console.WriteLine("Failed, " + response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
    }
}
    
public class OutgoingSMS
{
    public string Sender { get; set; }
    public List<string> Recipients { get; set; }
    public string Body { get; set; }
    public string Type { get; set; }
    public string Datacoding { get; set; }
    public int Priority { get; set; }
    public string Reference { get; set; }
    public List<string> 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($options);
// 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