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"
]
