SMS API Overview
The SMS API exposes the telco SMS functionality as an API. It allows you to interact with or notify humans or machines using long or short messages via SMS. The current version of the SMS API is focused around the sending of messages and the surrounding functionality of retrieving delivery information and counting text length.
Local and international
You will be able to send SMSs to Belgian destinations, but also to more than 200 worldwide destinations. In Belgium you can of course rely on Proximus as the biggest mobile operator, for international destinations you can count on recognized operators.
Simplify interactions
The SMS API allows you to use short codes to simplify your interactions with customers.
Pay as you grow
Try the API for free and pay as you grow! Check out our different pricing plans and choose one that fits your needs.
SMS API endpoint details
Base url: https://api.enco.io/sms/1.0.0
Header | Value | Required |
---|---|---|
Authorization | Bearer |
Yes |
Accept | application/json | Yes |
Content-type | application/json | Yes |
! The access_token should be retrieved via the authentication API.
Endpoint overview
/sms/outboundmessages POST
/sms/outboundmessages/{address} POST
/sms/outboundmessages/length POST
/sms/outboundmessages/deliveryinfos/{deliveryinfoId} GET
/sms/inboundmessages/shared GET
/sms/inboundmessages/{address} GET
/sms/dedicatedaddresses GET
/logs GET
Outbound
/sms/outboundmessages POST
Sends an SMS to the specified destination using a shared address such as "8937" as origin. This means that your application needs to send a message to a certain destination before it can get a response fom that destination. The routing of the response back to your application is not 100% guaranted as there may be other applications sending to the same destination. The shared number is free of charge, works "out-of-the-box" and is ideal if inbound SMS is not critical to your application.
Parameter | Description | Type | Required |
---|---|---|---|
forceCharacterLimit (query parameter) | Force max 1 message or allow message splitting | boolean | No |
**Request Payload **
{
"message": {string},
"destinations": [array of strings],
"callbackURL": {string}
}
! Destination number must be defined in the correct international format (e.g.: +32490000000). Note that although "Destinations" is an array, it is limited to only one destination. The callbackURL should be a valid http or https URL.
Response Payload
{
"resourceURL" : {string},
"deliveryInfo" : [ {
"address" : {string},
"deliveryStatus" : {string "DeliveredToTerminal", "DeliveryUncertain", "DeliveryImpossible", "MessageWaiting" or "DeliveredToNetwork"}
} ]
}
Example Call
curl -i -X POST 'https://api.enco.io/sms/1.0.0/sms/outboundmessages?forceCharacterLimit=false' -H 'Authorization: Bearer 674f4fc8db0000000083e887306cd8' -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{"message":"Hello World Test Message","destinations":["+32000000000"]}'
HTTP/1.1 201 Created
Server: nginx
Date: Tue, 22 Nov 2016 10:46:07 GMT
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST
X-Content-Type-Options: nosniff
Pragma: no-cache
Access-Control-Allow-Headers: authorization,Access-Control-Allow-Origin,Content-Type
X-Frame-Options: DENY
activityID: a90f1010-5e8b-4940-84fa-07a7a87c3d74
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Expires: 0
X-XSS-Protection: 1; mode=block
Location: https://api.enco.io/sms/1.0.0/sms/outboundmessages/deliveryinfos/b6494f29-0000-0000-be67-f6d42d9f787f"
Access-Control-Max-Age: 86400
{
"resourceURL" : "https://api.enco.io/sms/1.0.0/sms/outboundmessages/deliveryinfos/b6494f29-0000-0000-be67-f6d42d9f787f",
"deliveryInfo" : [ {
"address" : "+32000000000",
"deliveryStatus" : "DeliveredToNetwork"
} ]
}
! You can put line breaks in your message by using '\n' or '\r'.
Example
curl -i -X GET 'https://api.int.enco.io/sms/1.0.0/sms/outboundmessages?forceCharacterLimit=false' -H 'Authorization: Bearer aaaaaaaaaaaaa' -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{"message":"this is a test message\nwith line breaks\rand returns","destinations":["+32aaaaaaaa"]}'
sms/outboundmessages/{address} POST
Sends an SMS to the specified destination using one of your dedicated addresses as origin. You can get a list of your dedicated addresses with /sms/dedicatedaddresses. To set up a dedicated address, please contact us. As opposed to the shared number, the dedicated address is not free of charge and requires some time to be set up. Once you use a dedicated address, you are 100% guaranteed that inbound SMS will be properly routed back to your application. An other advantage is that your application can receive SMS from a certain destination without the need of your application sending an SMS to that destination first.
Parameter | Description | Type | Required |
---|---|---|---|
address | The dedicated address to be used as origin | string | Yes |
forceCharacterLimit (query parameter) | Force max 1 message or allow message splitting | boolean | No |
Request Payload
{
"message": {string},
"destinations": [array of strings],
"callbackURL": {string}
}
! Destination number must be defined in the correct international format (e.g.: +32490000000). Note that although "Destinations" is an array, it is limited to only one destination. The callbackURL should be a valid http or https URL.
Response Payload
{
"resourceURL" : {string},
"deliveryInfo" : [ {
"address" : {string},
"deliveryStatus" : {string "DeliveredToTerminal", "DeliveryUncertain", "DeliveryImpossible", "MessageWaiting" or "DeliveredToNetwork"}
} ]
}
Example Call
curl -i -X POST 'https://api.enco.io/sms/1.0.0/sms/outboundmessages/8888?forceCharacterLimit=false' -H 'Authorization: Bearer 674f4fc8db0000000083e887306cd8' -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{"message":"Hello World Test Message","destinations":["+32000000000"]}'
HTTP/1.1 201 Created
Server: nginx
Date: Tue, 22 Nov 2016 10:46:07 GMT
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST
X-Content-Type-Options: nosniff
Pragma: no-cache
Access-Control-Allow-Headers: authorization,Access-Control-Allow-Origin,Content-Type
X-Frame-Options: DENY
activityID: a90f1010-5e8b-4940-84fa-07a7a87c3d74
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Expires: 0
X-XSS-Protection: 1; mode=block
Location: https://api.enco.io/sms/1.0.0/sms/outboundmessages/deliveryinfos/b6494f29-0000-0000-be67-f6d42d9f787f"
Access-Control-Max-Age: 86400
{
"resourceURL" : "https://api.enco.io/sms/1.0.0/sms/outboundmessages/deliveryinfos/b6494f29-0000-0000-be67-f6d42d9f787f",
"deliveryInfo" : [ {
"address" : "+32000000000",
"deliveryStatus" : "DeliveredToNetwork"
} ]
}
/sms/outboundmessages/length POST
Calculates the length of the current text message and specifies how many more characters are allowed in the part before it is split into more parts.
Request Payload
{
"message": {string}
}
Response Payload
{
"numberOfChars" : {number},
"charLimitPerPart" : {number},
"numberOfParts" : {number},
"numberOfRemainingCharsInPart" : {number}
}
Example Call
curl -i -X POST 'https://api.enco.io/sms/1.0.0/sms/outboundmessages/length' -H 'Authorization: Bearer 66d126b000000000036897ccabd6' -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{"message":"Hello world test message"}'
HTTP/1.1 200 OK
Server: nginx
Date: Tue, 22 Nov 2016 10:31:38 GMT
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Vary: Accept-Encoding
X-Frame-Options: DENY
activityID: 5908d31b-1598-42b4-b613-67d441564d29
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST
X-Content-Type-Options: nosniff
Expires: 0
Pragma: no-cache
X-XSS-Protection: 1; mode=block
Access-Control-Allow-Headers: authorization,Access-Control-Allow-Origin,Content-Type
Access-Control-Max-Age: 86400
{
"numberOfChars" : 24,
"charLimitPerPart" : 160,
"numberOfParts" : 1,
"numberOfRemainingCharsInPart" : 136
}
/sms/outboundmessages/deliveryinfos/{deliveryinfoId} GET
Retrieves the delivery info for the specified id.
Parameter | Description | Type | Required |
---|---|---|---|
deliveryinfoId | The deliveryinfoId linked to the previous outboundmessages POST request | String | Yes |
Response Payload
{
"resourceURL" : {string},
"deliveryInfo" : [ {
"address" : {string},
"deliveryStatus" : {string "DeliveredToTerminal", "DeliveryUncertain", "DeliveryImpossible", "MessageWaiting" or "DeliveredToNetwork"}
} ]
}
Example Call
curl -i -X GET 'https://api.enco.io/sms/1.0.0/sms/outboundmessages/deliveryinfos/ff595443-0000-0000-9b83-d9acd74fa67c' -H 'Authorization: Bearer 674f4fc8d00000000003e887306cd8' -H 'Accept: application/json'
HTTP/1.1 200 OK
Server: nginx
Date: Tue, 22 Nov 2016 10:59:02 GMT
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Vary: Accept-Encoding
X-Frame-Options: DENY
activityID: a365be3c-3875-419f-8d83-33e5474f13d1
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET
X-Content-Type-Options: nosniff
Expires: 0
Pragma: no-cache
X-XSS-Protection: 1; mode=block
Access-Control-Allow-Headers: authorization,Access-Control-Allow-Origin,Content-Type
Access-Control-Max-Age: 86400
{
"resourceURL" : "https://api.enco.io/sms/1.0.0/sms/outboundmessages/deliveryinfos/ff595443-0000-0000-9b83-d9acd74fa67c",
"deliveryInfo" : [ {
"address" : "tel:+32000000000",
"deliveryStatus" : "DeliveredToTerminal"
} ]
}
Inbound
/sms/inboundmessages/shared GET
Retrieves the inbound messages on which your application has ownership for the shared address (e.g. "8937"). Your application automatically gets ownership of an inbound message based on the following criteria: your application has sent a message to the sender of that message and there is no other application that has also sent a message to the same destination within a period of 7 days.
Parameter | Description | Type | Required |
---|---|---|---|
startdatetime (query param) | Only messages higher than the startdatetime will be retrieved | datetime | Yes |
enddatetime (query param) | Only messages lower than the enddatetime will be retrieved | datetime | Yes |
new-only (query param) | If set to true than only messages will be retrieved that haven't been retrieved before | boolean | Yes |
Response Payload
{
"numberOfMessages" : {integer},
"messages" : [ {
"senderAddress" : { string},
"message" : {string},
"numberOfParts" : {integer},
"timeReceived" : {string}
} ]
}
/sms/inboundmessages/{address} GET
Retrieves all inbound messages sent to the dedicated address specified.
Parameter | Description | Type | Required |
---|---|---|---|
address (path param) | The dedicated address that received the messages | string | Yes |
startdatetime (query param) | Only messages higher than the startdatetime will be retrieved | datetime | Yes |
enddatetime (query param) | Only messages lower than the enddatetime will be retrieved | datetime | Yes |
new-only (query param) | If set to true than only messages will be retrieved that haven't been retrieved before | boolean | Yes |
Response Payload
{
"numberOfMessages" : {integer},
"messages" : [ {
"senderAddress" : { string},
"message" : {string},
"numberOfParts" : {integer},
"timeReceived" : {string}
} ]
}
Other
/sms/dedicatedaddresses GET
Retrieves all the dedicated addresses that you can use as origin address for sending messages.
Response Payload
{
"dedicatedAddresses": [array of strings]
}
Example Call
curl -i -X GET 'https://api.int.enco.io/sms/1.0.0/sms/dedicatedaddresses' -H 'Authorization: Bearer 4f3af6e00000000000000233ca' -H 'Accept: application/json' -H "Content-type: application/json"
HTTP/1.1 200 OK
Server: nginx
Date: Tue, 24 Jan 2017 12:43:49 GMT
Transfer-Encoding: chunked
Connection: keep-alive
X-Frame-Options: DENY
activityID: 468a87a5-a82b-42d4-bf40-2d467ee247b0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET
X-Content-Type-Options: nosniff
Expires: 0
Pragma: no-cache
X-XSS-Protection: 1; mode=block
Access-Control-Allow-Headers: authorization,Access-Control-Allow-Origin,Content-Type
Access-Control-Max-Age: 86400
{
"dedicatedAddresses" : [ "666", "8888" ]
}
/logs GET
Returns the logging overview of the SMS API
Parameter | Description | Type | Required |
---|---|---|---|
type | The type of logs to be retrieved. , "sms-outbound": successful API calls , "sms-outbound-error": erroneous API calls | string | yes |
dedicatedaddress | dedicated address for which logs should be retrieved. If not provided, logs will be retrieved for shared address | string | no |
year | The year to search in | integer | yes |
month | The month to search in | integer | yes |
function | Function to execute on the logs, "interval": retrieves all results in the specified interval, "groupByDay": retrieves an overview of the month specified | string | yes |
startTime | mandatory with "interval" function | datetime | no |
endTime | mandatory with "interval" function | datetime | no |
page | Used for paging. You can specify "first", "next", "previous" or "last" page. | string | no |
pageref | Used for paging. Identifies where to start the next or previous page. | string | no |
limit | Limits the amount of results to be returned | integer | no |
Response Payload
[
{
"timestamp" : {string ISO8601},
"destinationAddress" : {string international number format},
"message" : {string},
"initialDeliveryInfo" : {string},
"numberOfChars" : {string},
"numberOfMessages" : {string},
"requestId" : {string},
"httpResponseCode" : {string}
},
...
]
Example Call
curl -i -X GET 'https://api.int.enco.io/sms/1.0.0/logs?type=sms-outbound&year=2016&month=12&function=interval&startTime=2016-12-27T23:00:00.000Z&endTime=2016-12-28T23:00:00.000Z&limit=10' -H 'Authorization: Bearer 6586d1234561665dce5888888ea90d' -H 'Accept: application/json'
HTTP/1.1 200 OK
Server: nginx
Date: Wed, 28 Dec 2016 16:19:47 GMT
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Vary: Accept-Encoding
X-Frame-Options: DENY
activityID: 618a77e5-37ce-40f0-8afd-e1cce2cccd7f
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET
X-Content-Type-Options: nosniff
Expires: 0
Pragma: no-cache
X-XSS-Protection: 1; mode=block
Access-Control-Allow-Headers: authorization,Access-Control-Allow-Origin,Content-Type
Access-Control-Max-Age: 86400
[ {
"timestamp" : "2016-12-28T16:51:40.727+01:00",
"destinationAddress" : "+32470000000",
"message" : "lolololol",
"initialDeliveryInfo" : "MessageWaiting",
"numberOfChars" : "9",
"numberOfMessages" : "1",
"requestId" : "6a2f5fed-0000-0000-0000-412502c68939",
"httpResponseCode" : "200"
}, {
"timestamp" : "2016-12-28T17:13:13.149+01:00",
"destinationAddress" : "+32470000000",
"message" : "This is a test message!",
"initialDeliveryInfo" : "MessageWaiting",
"numberOfChars" : "23",
"numberOfMessages" : "1",
"requestId" : "06e89922-0000-0000-0000-d2e690bd3e9d",
"httpResponseCode" : "200"
} ]