Introduction
Welcome to the SMSO API! You can use our API to access SMSO API endpoints.
We have language bindings in Shell, PHP, JavaScript! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.
Authentication
To authorize, use this code:
# With shell, you can just pass the correct header with each request
curl -H "X-Authorization: API-KEY" "https://app.smso.ro/api/v1/"
# full example as query string
curl "https://app.smso.ro/api/v1/send?sender=4&to=0722334455&body=Message%20Body&apiKey=API-KEY"
<?php
// via file_get_contents
$opts = [
"http" => [
"method" => "POST",
"header" => "X-Authorization: API-KEY"
]
];
$context = stream_context_create($opts);
$content = file_get_contents('https://app.smso.ro/api/v1/', false, $context);
var_dump($content);
// via guzzle
use GuzzleHttp\Client;
$client = new Client;
$request = $client->request('GET', 'https://app.smso.ro/api/v1/', [
'headers' => [
'X-Authorization' => 'API-KEY',
],
]);
var_dump(json_decode($request->getBody()->getContents()));
// soon
Make sure to replace
API-KEYwith your Tean's API key from our developer page.
SMSO uses API keys to allow access to the API. You can register a new SMSO API key at our developer page.
SMSO expects for the API key to be included in all API requests to the server in a header that looks like the following:
- Via a header:
X-Authorization: API-KEY - Via a query string, either POST OR GET, just append it to the URL like &apiKey=API-KEY
The Source App identifies the application or platform sending the SMS (eg. Magento/2.4.8). Can be sent either as a request header or as a body parameter:
- Via header:
X-Source-App: Magento/2.4.8 - Via body parameter
"source_app": "Magento/2.4.8"
Senders
Get the list of available senders
curl -H "X-Authorization: API-KEY" "https://app.smso.ro/api/v1/senders"
<?php
use GuzzleHttp\Client;
$client = new Client;
$request = $client->request('GET', 'https://app.smso.ro/api/v1/senders', [
'headers' => [
'X-Authorization' => 'API-KEY',
],
]);
// nothing yet
The above command returns JSON structured like this:
[
{
"id":4,
"name":"1847",
"pricePerMessage":3
},
...
]
This endpoint retrieves all the available senders in the the team.
HTTP Request
GET https://app.smso.ro/api/v1/senders
Query Parameters
None
Messages
Sending a message
curl --request POST --header 'X-Authorization: smso-api-key' "https://app.smso.ro/api/v1/send" \
-d "sender=4" \
-d "to=+40722334455" \
-d "body=Testing"
<?php
use GuzzleHttp\Client;
$client = new Client;
$request = $client->request('POST', 'https://app.smso.ro/api/v1/send', [
'headers' => [
'X-Authorization' => 'smso-api-key',
],
'form_params' => [
'to' => '',
'body' => '',
'sender' => '',
],
]);
var_dump(json_decode($request->getBody()->getContents()));
// nothing yet
The above command returns JSON structured like this:
{
"status": 200,
"responseToken": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"transaction_cost" : 3.5 // in eurocents
}
This endpoint sends an SMS Message
HTTP Request
POST https://app.smso.ro/api/v1/send
Query Parameters
| Parameter | Required? | Description |
|---|---|---|
| to | Yes | E.164 Format. The + is optional |
| sender | Yes | The ID of the sender |
| body | Yes | Contents of the message |
| type | No | Type of the message. Can be 'marketing', 'transactional' or 'otp', based on the type of communication the message is intended for. Used to filter out unsubscribed users when set to 'marketing'. |
| source_app | No | Identify the application or platform that sent the SMS (e.g., 'Magento/2.4.8'). The X-Source-App header takes precedence. |
| webhook | No | Identical to webhook_status, preserved for legacy purposes |
| webhook_status | No | Webhook for receiving the SMS message status |
| webhook_responses | No | Webhook for receiving the SMS message reply |
| source_app | No | Identifies the application that initiated the request. Can be sent either as the X-Source-App request header (recommended) or as this source_app body parameter — the header takes precedence. Allowed characters: letters, digits, -, ., _, / (separators cannot be first/last or doubled), e.g. Magento/2.4.8. Stored on the message so you can trace which integration sent it. Requests with an invalid format receive a 400 response. |
| generate_unsubscribe_link | No | Possible values 1/0. If 1, replaces the [unsubscribe] tag from the body with a generated short URL unsubscribe link. Only for 'marketing' message type! |
| remove_special_chars | No | Possible values 1/0. If 1, replaces special characters like diacritics with ASCII characters (Ex.: ĂÂ = A, Ș = S, etc.) |
Checking the message status
curl --request POST "https://app.smso.ro/api/v1/status" \
-d "responseToken=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
// also GET
curl "https://app.smso.ro/api/v1/status?responseToken=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
<?php
use GuzzleHttp\Client;s
$client = new Client;
$request = $client->request('GET', 'https://app.smso.ro/api/v1/status?responseToken=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee');
// also POST
$request = $client->request('POST', 'https://app.smso.ro/api/v1/status', [
'form_params' => [
'responseToken' => 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
],
]);
var_dump(json_decode($request->getBody()->getContents()));
// soon
The above command returns JSON structured like this:
{
"status": 200,
"data": {
"status": "delivered",
"sent_at": "2019-05-1 15:18:20",
"delivered_at": "2019-05-1 15:18:25",
"receiver": {
"number": "+40722334455",
"mcc": "226",
"mnc": "01"
}
}
}
This endpoint sends an SMS Message
HTTP Request
POST or GET https://app.smso.ro/api/v1/status
Query Parameters
| Parameter | Required? | Description |
|---|---|---|
| responseToken | Yes | The uuid from the SEND |
Bulk Send
curl --request POST --header 'X-Authorization: smso-api-key' "https://app.smso.ro/api/v1/send/bulk" \
-H "Content-Type: application/json" \
-d '{
"sender": 4,
"to": ["+40722111111", "+40722222222", "+40722333333"],
"body": "Mesaj comun pentru toate numerele"
}'
curl --request POST --header 'X-Authorization: smso-api-key' "https://app.smso.ro/api/v1/send/bulk" \
-H "Content-Type: application/json" \
-d '{
"sender": 4,
"messages": [
{ "to": "+40722111111", "body": "Salut, Ana!" },
{ "to": "+40722222222", "body": "Salut, Ion!" }
]
}'
<?php
use GuzzleHttp\Client;
$client = new Client;
$request = $client->request('POST', 'https://app.smso.ro/api/v1/send/bulk', [
'headers' => [
'X-Authorization' => 'smso-api-key',
'Content-Type' => 'application/json',
],
'json' => [
'sender' => 4,
'to' => ['+40722111111', '+40722222222'],
'body' => 'Mesaj comun pentru toate numerele',
],
]);
var_dump(json_decode($request->getBody()->getContents()));
// nothing yet
The above command returns JSON structured like this:
{
"status": 200,
"responseToken": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
}
This endpoint sends multiple SMS messages in a single request.
Maximum 100 de mesaje/request. Sunt disponibile două formate:
"to": listă de numere +"body": text comun pentru toate numerele."messages": listă de obiecte, fiecare cu propriile câmpuri"to"și"body".
Nu se trimit simultan "to" și "messages".
HTTP Request
POST https://app.smso.ro/api/v1/send/bulk
Parametri generali — la nivel de request
| Parameter | Required? | Description |
|---|---|---|
| apiKey | No | Cheia API; necesară dacă lipsește headerul X-Authorization. |
| to | Yes (formatul cu text comun) | Listă de 1–100 de numere, pentru formatul cu text comun. |
| body | Yes (formatul cu text comun) | Textul comun; obligatoriu când se folosește lista "to". |
| messages | Yes (formatul per mesaj) | Listă de 1–100 de obiecte mesaj, alternativă la lista "to". |
| source_app | No | Aplicația sursă, de exemplu "CRM/1.0". Alternativ: headerul X-Source-App, care are prioritate. Format bulk: nume din litere + / + versiune nevidă. |
Parametri care pot fi generali SAU per mesaj
Valorile generale se aplică tuturor mesajelor. O valoare specificată în messages[] suprascrie valoarea generală.
| Parameter | Required? | Description |
|---|---|---|
| sender | Yes (general, pentru formatul cu "to") |
ID-ul unui sender accesibil contului. Obligatoriu general pentru formatul cu "to". Pentru "messages", se poate defini general sau în fiecare mesaj. |
| label | No | Eticheta/numele expeditorului; implicit, numele senderului selectat. |
| type | No | marketing / transactional / otp / spam / priority. Implicit: transactional. Configurația contului poate impune alt tip. |
| webhook | No | URL alternativ pentru notificările de status; folosit când webhook_status lipsește sau este null. |
| webhook_status | No | URL pentru notificările de schimbare a statusului. |
| webhook_responses | No | URL pentru notificările privind răspunsurile SMS primite, unde serviciul permite răspunsuri. |
| ttl | No | Integer, minimum 60; valabilitatea mesajului în secunde. Implicit în configurația actuală: 43200 (12 ore). |
| generate_unsubscribe_link | No | Boolean, implicit false. Dacă este true, înlocuiește [unsubscribe] din text cu un link de dezabonare. |
| remove_special_chars | No | Boolean, implicit true. Aplică conversia caracterelor speciale, inclusiv diacritice și emoji. Cu false se păstrează textul original. |
Parametri specifici fiecărui obiect din messages[]
| Parameter | Required? | Description |
|---|---|---|
| to | Yes | Un singur număr ca string; recomandat format internațional: "+40722111111". |
| body | Yes | Textul mesajului. Nu se moștenește din body general. |
| variables | No | Obiect cu substituții pentru text. Exemplu: {"name":"Ana"} înlocuiește [name]. Valorile pot fi string, număr, boolean sau null și sunt convertite în string. |
| opțiuni comune | No | Oricare dintre opțiunile comune enumerate mai sus: sender, label, type, webhook, webhook_status, webhook_responses, ttl, generate_unsubscribe_link, remove_special_chars. |
Bulk Status
curl --request POST --header 'X-Authorization: smso-api-key' "https://app.smso.ro/api/v1/status/bulk" \
-H "Content-Type: application/json" \
-d '{
"log_ids": ["aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "bbbbbbbb-cccc-dddd-eeee-ffffffffffff"]
}'
<?php
use GuzzleHttp\Client;
$client = new Client;
$request = $client->request('POST', 'https://app.smso.ro/api/v1/status/bulk', [
'headers' => [
'X-Authorization' => 'smso-api-key',
'Content-Type' => 'application/json',
],
'json' => [
'log_ids' => [
'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
'bbbbbbbb-cccc-dddd-eeee-ffffffffffff',
],
],
]);
var_dump(json_decode($request->getBody()->getContents()));
// nothing yet
This endpoint returns the status for multiple messages in a single request.
HTTP Request
POST https://app.smso.ro/api/v1/status/bulk
Query Parameters
| Parameter | Required? | Description |
|---|---|---|
| apiKey | No | Cheia API, dacă nu este transmisă prin header. |
| log_ids | Yes | Listă de 1–1000 de UUID-uri. Se folosesc valorile responseToken primite de la send. |
Message Statuses
// nothing
// nothing
// nothing
The above command returns JSON structured like this:
// nothing
Message status description
The message can take a number of states.
Status Descriptions
| Status | Final | Description |
|---|---|---|
| dispatched | No | The message is in the process of sending to the network. (rarely seen) |
| sent | No | The message has been sent to the network. |
| delivered | Yes | The message has been delivered to the phone. |
| undelivered | Yes | The message was undelivered. |
| expired | Yes | The message is expired. |
| error | Yes | There was an error sending the message. |
Webhooks
Message status
# use this command to simulate an incomming request to test yout webhook
curl --request POST "https://your-server.com/your-webhook-endpoint" \
-d "uuid=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" \
-d "status=sent" \
-d "sent_at=2019-05-01 12:30:09" \
-d "delivered_at=2019-05-01 12:20:09" \
-d "receiver[number]=+40722334455" \
-d "receiver[mcc]=226" \
-d "receiver[mnc]=03"
// nothing yet
// nothing yet
You can use an app like postb.in to test incoming requests.
// no output
This is an endpoint on your application side that handles the status of the message.
HTTP Request
POST https://your-server.com/your-webhook-endpoint
Query Parameters
| Parameter | Can be empty? | Description |
|---|---|---|
| uuid | No | Uuid received from sending the message |
| status | No | Message status |
| sent_at | No | Time sent to the network |
| delivered_at | Yes | Time delivered to phone |
| receiver['number'] | No | Receiving number in E.164 Format. |
| receiver['mcc'] | No | Mobile Country Code |
| receiver['mnc'] | No | Mobile Network Code |
Receiving messages
# use this command to emulate a webhopok
curl --request POST "https://your-server.com/your-webhook-endpoint" \
-d "body=Nu raspunzi la sms..." \
-d "replied_to=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" \
-d "received_at=2019-05-01 12:30:09" \
-d "sender['number']=+40722334455" \
-d "sender['mcc']=226" \
-d "sender['mnc']=03"
// soon
// soon
You can use an app like https://postb.in/ to test incoming requests.
This is an endpoint on your application side that handles receiving messages.
HTTP Request
POST https://your-server.com/your-webhook-endpoint
Query Parameters
| Parameter | Can be empty? | Description |
|---|---|---|
| body | Yes | Contents of the message |
| replied_to | Yes | Uuid of the message that the number received and is now responding to |
| received_at | No | Time the message was received |
| sender['number'] | No | Sender number in E.164 Format. |
| sender['mcc'] | No | Mobile Country Code |
| sender['mnc'] | No | Mobile Network Code |
Errors
The SMSO API uses the following error codes:
| Error Code | Meaning |
|---|---|
| 200 | OK |
| 400 | Your request is invalid. See errors attached. |
| 401 | Authorization required, API key is not valid. |
| 402 | You don't have enough credit to send the message. |
| 403 | The message contains blacklisted words. |
| 405 | User has unsubscribed from this service. |
| 409 | You've exceeded the allowed number of messages per minute. Please slow down and retry after a short delay. |
| 422 | User is not allowed to send international messages. |
Credit
Checking remaining credit
curl --request GET --header 'X-Authorization: smso-api-key' "https://app.smso.ro/api/v1/credit-check"
<?php
use GuzzleHttp\Client;
$client = new Client;
$request = $client->request('GET', 'https://app.smso.ro/api/v1/credit-check', [
'headers' => [
'X-Authorization' => 'smso-api-key',
],
]);
var_dump(json_decode($request->getBody()->getContents()));
// nothing yet
The above command returns JSON structured like this:
{
"status" : 200,
"credit_value" : 4847.72
}
This endpoint returns the remaining credit for the team
HTTP Request
GET https://app.smso.ro/api/v1/credit-check
Query Parameters
None.