Send SMS
Quick start
Using the example below, replace ”API_NYCKEL” with a bearer token that you create in the user portal.
curl -X POST "https://api.ip1sms.com/v2/batches" \
-H "Authorization: Bearer API_NYCKEL" \
-H "Content-Type: application/json" \
-d '{
"sender": "iP1",
"recipients": [
"RECIPIENT-NUMBER"
],
"body": "A nice message sent from iP.1 SMS API"
}'
call
Endpoint: /v2/batches
Methodology: POST
Content-Type: application/json
Example of call data
{ "sender": "iP1", "recipients":[ "456189040623", "175368927054", "392094880589", "568798567631" ], "body": "A very nice message", }
The example above contains the call data with the required fields sender, recipients and body, which is required to send an SMS message. See under the heading Fields for call data for a list of all fields and their descriptions.
Fields for call data
| Field name | Mandatory | Type | Description and Conditions | Example |
|---|---|---|---|---|
| sender | Yes | String |
A Call will be rejected if sender:
|
|
| recipients | Yes | Array |
A Call will be rejected if recipients:
|
|
| recipients - templating | No, it is not. | Nestat Object |
To use the template system, you need to convert your previous receiver array to a dictionary of dictionaries. The upper level key is the recipient's MSISDN (telephone number). The second-level key is then searched for in the text and replaced with the second-level value. |
|
| body | Yes | String |
A call will fail if body:
|
|
| type | No, it is not. | String |
There are two types: sms and flash.
sms.
|
|
| datacoding | No, it is not. | String |
There are two types that are available:
gsm is set, messages that require
ucs (extended characters) to be denied. The default is
ucs.
|
.
|
| priority | No, it is not. | Integer |
Used for messages that need to be delivered quickly. Allowed values
are 1 (standard, minimum) and 2 (highest).
Setting priorities 2 increases the price per SMS (10 öre for
Swedish account, €0.01 for international account).
|
|
| deliveryWindows | No, it is not. | Array |
Possibility to schedule mailings during specific time windows (e.g.
weekdays 10:00-10:15). You can have multiple windows.
Parsing rules:
|
|
| deliveryReportUrl | No, it is not. | String |
If a URL is specified, status updates (delivery reports) are sent there
via POST. The reports are separated for each recipient
and status.
|
|
| reference | No, it is not. | String |
Allows the user to set a custom ID or credential.
Restrictions:
null is default value.
|
|
| tags | No, it is not. | string |
An array of tags used to categorize or sort batches. Allows filtering when listing batches. |
|
Response
The response to a call consists of a JSON with fields describing the content of the batch.
Example of response data
Below you will find an example of a response to a successful request against the batch endpoint. See under the heading Fields for response data for a detailed description of all fields in the response.
{
"id": "5bc86b6e85c7209830f96936",
"sender": "46101606060",
"body": "Hi my name is {name}",
"owner": "ip1-XXXXX",
"direction": "MT",
"type": "flash",
"datacoding": "GSM",
"priority": 1,
"templated": true,
"priceSummary": {
"total": 0.125,
"currency": "EUR",
"average": 0.0416
},
"messageSummary": {
"101": {
"messages": 43,
"sms": 86
},
"102": {
"messages": 3,
"sms": 6
},
"201": {
"messages": 142,
"sms": 284
}
},
"deliveryWindows": [
{
"opens": "ISO-8601 string",
"closes": "ISO-8601 string"
},
{
"opens": "ISO-8601 string",
"closes": "ISO-8601 string"
}
],
"status": 112,
"deliveryReportUrl": "https://api.example.com/sms/deliveryreport",
"reference": "A client reference",
"tags": ["marketing", "auth", "etc"],
}
Fields for response data
| Field name | Type | Description | Example | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | String |
Batch ID. | |
||||||||||||||||||
| sender | String |
The sender ID used in the messages. | |
||||||||||||||||||
| body | String |
The original body, i.e. the message text, which is sent, before templates have been applied, according to the original request. |
|
||||||||||||||||||
| owner | String |
The account number of the SMS account that owns the batch | |
||||||||||||||||||
| direction | String |
Tells you if the message sent or received by our system
|
|
||||||||||||||||||
| type | String |
Describes the type of message.
|
|
||||||||||||||||||
| datacoding | String |
Tells you which character set is used for the batch.
|
.
|
||||||||||||||||||
| priority | Integer |
Describes the priority used for the batch. |
|
||||||||||||||||||
| templated | boolean |
Indicates if the batch body (message text) contains templating. |
|
||||||||||||||||||
| priceSummary | array |
Gives a summary of the cost of the batch and the currency that debited the account. |
|
||||||||||||||||||
| messageSummary | array |
Gives a summary of the number of messages in the batch divided into status groups. |
|
||||||||||||||||||
| deliveryWindows | Array |
Displays the batch time window | |
||||||||||||||||||
| status | Integer | Current status of the batch. Derived from the direction and latest status of the batch's messages. Available statuses are as follows:
|
|
||||||||||||||||||
| deliveryReportUrl | String |
Displays any callback url for receiving delivery reports to external software. |
|
||||||||||||||||||
| reference | String |
Displays the batch reference if available. |
|
||||||||||||||||||
| tags | string |
shows any tags in the batch. |
|
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",
};
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 Recipients { get; set; }
public string Body { 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",
);
$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"
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
End Class
Troubleshooting
In this section, you will find HTTP error status codes and common errors for individual call fields.
Common error status codes
| Code | Name | Significance | Class |
|---|---|---|---|
| 400 | Bad Request | The server cannot understand the request, often due to invalid syntax (e.g. incorrectly formatted JSON data). | client panel |
| 401 | Unauthorized | The client must authenticate to access the resource (e.g. an API key or login token is missing). | client panel |
| 403 | Forbidden | The client has authenticated, but is not authorized to perform the action (e.g. a regular user trying to delete other people's data). | client panel |
| 404 | Not Found | The server has not found the resource that was requested (e.g. a specific resource with an ID that does not exist). | client panel |
| 405 | Method Not Allowed | The HTTP method used is not allowed for the resource (e.g. trying to POST to a resource that only accepts GET). | client panel |
| 409 | Conflict | The request could not be completed due to a conflict with the current state of the resource (e.g. trying to create a resource that already exists). | client panel |
| 500 | Internal Server Error | A generic error message indicating that an unexpected condition on the server prevented it from fulfilling the request. | Server error |
| 503 | Service Unavailable | The server is currently unavailable (e.g. overloaded or down for maintenance). | Server error |
Troubleshooting specific fields
Each incorrect call that triggers an error status code contains a detailed description in the response body. You can extract this text programmatically to get a clearer picture of what went wrong. If you can't read the error in the response body, you can use the list below to troubleshoot your failed call.
sender
- Make sure that the additional service "Optional sender" is activated on your account. You can activate "Optional Sender" in the webshop or via one of our online services.
- Ensure that the sender is registered on the account in the user portal.
- If the sender consists of a number, ensure that the number is no longer than 15 digits.
- If an alphanumeric sender is used, ensure that it consists of 3 - 11 characters, Aa - Zz, 0 - 9.
body
- Ensure that the message text does not exceed 2000 characters.
- Check the text content to rule out inappropriate or regulated content which may trigger blocking services with some operators.
recipients
- Make sure that the number you are trying to send to is in the format MSISDN (4612345678), i.e. a number with a country code, without + or double zeros in front.