Μετάβαση σε: πλοήγηση, αναζήτηση

REST API

REST API v. 3.0 - Documentation and samples

https://rest.smsme.gr/

SMSme REST API provides a simple and flexible way to integrate SMS communication to your services. Swagger


Authentication

Each request to the SMSme API must be signed with an API token. For this, obtain an API token from the

POST: /Users/authenticate

endpoint. Then set this key to the Authorization: Bearer header value

Example:

Request Parameters:

username: If you created your account from https://smsme.gr then your user name is your email address.
password: Your account password

Request:

curl -X POST "https://rest.smsme.gr/Users/authenticate" -H "accept: text/plain, application/json, text/json" -H "Content-Type: application/json-patch+json" -d "{ \"username\": \"string\", \"password\": \"string\"}" 

Response

{
 "token": "xxx.xxx.xxx",
 "expirationDate": "2018-06-27T09:00:00.0000+03:00"
}


Account Balance

Retrieve your account balance

GET: /Users/balance


Example:

Request Parameters:

None

Request

curl -X GET "https://rest.smsme.gr/Users/balance" -H "accept: text/plain, application/json, text/json" -H "Authorization: Bearer xxx.xxx.xxx"

Response

{
 "balance": 143.182
}


Pricing

Retrieve your accounts pricing per country and service provider

GET: /Pricing/list


Example:

Request Parameters:

None

Request

curl -X GET "https://rest.smsme.gr/Pricing/list" -H "accept: text/plain, application/json, text/json" -H "Authorization: Bearer xxx.xxx.xxx"

Response

{
 "countries": [
   {
     "code": "30",
     "country": "Greece",
     "operators": [
       {
         "name": "COSMOTE",
         "mccMnc": "20201",
         "price": 0.04
       },
       {
         "name": "VODAFONE",
         "mccMnc": "20205",
         "price": 0.04
       },
       {
         "name": "Q-TELECOM",
         "mccMnc": "20209",
         "price": 0.04
       },
       {
         "name": "WIND",
         "mccMnc": "20210",
         "price": 0.04
       },
       {
         "name": "Cyta",
         "mccMnc": "20214",
         "price": 0.04
       }
     ]
   }
 ]
}

Delivery Reports

Retrieve delivery reports of submitted messages accounts pricing per country and service provider

POST: /Reports/create


Example:

Request Parameters:

trackingId: The tracking Id you have received for a submitted message (Optional)
sender: The sender of the message (Optional)
recipient: The mobile number of the recipient (Optional)
dateTimeFrom: The date and time of submitted messages where the look up starts (Required)
dateTimeTo: The date and time of submitted messages where the look up ends (Required)


Request

curl -X POST "https://rest.smsme.gr/Reports/create" -H "accept: text/plain" -H "Authorization: Bearer xxx.xxx.xxx" -H "Content-Type: application/json-patch+json" -d "{ \"dateTimeFrom\": \"2019-01-04T20:24:57.721Z\", \"dateTimeTo\": \"2019-01-05T20:24:57.721Z\", \"recipient\": \"306912345678\"}"

Response

{
 "deliveryReports": [
   {
     "trackingId": 7703482,
     "reportDateTime": "2019-01-15T07:44:02",
     "reportStatus": "Delivered",
     "recipient": "306912345678",
     "cost": 0.04,
     "operator": "VODAFONE",
     "mccMnc": "20205"
   },
   {
     "trackingId": 7693601,
     "reportDateTime": "2019-03-05T21:16:58",
     "reportStatus": "Delivered",
     "recipient": "306912345678",
     "cost": 0.04,
     "operator": "COSMOTE",
     "mccMnc": "20201"
   }
 ]
}

Report Status States

Waiting for delivery : Message has been submitted to the Operator
Delivered : Message was delivered to recipient
Failed : Delivery has failed
Expired : Delivery failed after 48 hours (Timeout)


Send SMS

Submit SMS messages to one or multiple recipients

POST: /Sms/send


Example:

Request Parameters:

sender: The name or the number of the sender that will be displayed on recipients device (Required up to 11 alphanumeric characters) 

Restrictions apply based on Country/Operator Policy.


recipients: The recipients mobile phone number  including country code without leading zero(s) (Required array of numeric strings. Up to 1000 recipients per request ) 

Please note that if a recipient is included in your black list then this recipient will be excluded from the recipients list and no message will be delivered.


message: The message that will be displayed on recipients device (Required up to 918 characters) 

One SMS is 160 characters, when you send more that 160 characters, SMSme will automatically create and concatenate multiple SMS messages that users device receives as one long SMS. This process is called "Concatenation". In order to calculate the total cost of your message use the following rule: Ceiling(total message characters / 153) * sms cost per recipient. For example if your message is 161 characters you will be charges for 2 SMS. Please note that the euro sign "€" is calculated as two characters.


deliveryDateTime: The date and time were the SMS will be send (Required) 

This field will help you schedule SMS for future delivery.


Request

curl -X POST "https://rest.smsme.gr/Sms/send" -H "accept: text/plain" -H "Authorization: Bearer xxx.xxx.xxx" -H "Content-Type: application/json-patch+json" -d "{ \"sender\": \"SMSem\", \"recipients\": [ \"306912345678\" ], \"message\": \"Test SMS with one recipient\", \"deliveryDateTime\": \"2019-05-04T20:47:46.446Z\"}"

Response

{
 "totalSms": 1,
 "totalCost": 0.04,
 "trackRecipients": [
   {
     "recipient": "306912345678",
     "trackId": 7812530
   }
 ]
}

Please not that it is important to collect track Ids in you application. Track Ids can be used in order to cancel scheduled SMS deliveries and are also useful in support cases.



Cancel SMS

Cancel one or more submitted SMS messages. Please not that you can only cancel message that have beed schedule for future delivery. SMS can be canceled up to one minute before "deliveryDateTime"

DELETE: /Sms/cancel


Example:

Request Parameters:

trackIds: One or more track Ids that you have collected after sending SMS  (Required array of numeric strings) 

Please not that you can only cancel message that have beed schedule for future delivery. SMS can be canceled up to one minute before "deliveryDateTime"


Request

curl -X DELETE "https://rest.smsme.gr/Sms/cancel" -H "accept: text/plain" -H "Authorization: Bearer xxx.xxx.xxx" -H "Content-Type: application/json-patch+json" -d "{ \"trackIds\": [ 1233, 1234, 1235 ]}"

Response

{
 "cancellationResults": [
   {
     "trackId": 1235,
     "successful": true,
     "message": ""
   },
  {
     "trackId": 1234,
     "successful": true,
     "message": ""
   },
  {
     "trackId": 1233,
     "successful": false,
     "message": "Already send or not found"
   }
 ]
}



Black List Add

Add recipients to Blacklist. Once a recipient is added to the black list no SMS can be delivered to the recipient from your account.

POST: /Blacklist/add


Example:

Request Parameters:

mobile: The recipients mobile phone number  including country code without leading zero(s) (Required)


Request

curl -X POST "https://rest.smsme.gr/Blacklist/add" -H "accept: text/plain" -H "Authorization: Bearer xxx.xxx.xxx" -H "Content-Type: application/json-patch+json" -d "{ \"mobile\": \"306912345678\"}"

Response HTTP OK 201

{
 "mobile": "306912345678"
}


Black List Remove

Remove recipients from Blacklist.

DELETE: /Blacklist/remove


Example:

Request Parameters:

mobile: The recipients mobile phone number  including country code without leading zero(s) (Required)


Request

curl -X DELETE "https://rest.smsme.gr/Blacklist/remove" -H "accept: text/plain" -H "Authorization: Bearer xxx.xxx.xxx" -H "Content-Type: application/json-patch+json" -d "{ \"mobile\": \"306912345678\"}"

Response HTTP OK 200



Black List List

Remove recipients from Blacklist.

GET: /Blacklist/list


Example:

Request Parameters: None

Request

curl -X GET "https://rest.smsme.gr/Blacklist/list" -H "accept: text/plain" -H "Authorization: Bearer xxx.xxx.xxx"

Response [

 "306912345678",
 "306912345679"

]