SMS messages
The controller can be used to send individual SMS Messages. The default for all parameters must be coded in UTF-8.
General notes
Telephone numbers must be in formats of 9 or 11 digits. It is possible to add the “+” character as a country prefix.
The content of individual messages is typically 160 characters or 70 characters if a single special character is used. The maximum is 459 characters (or 200 with special characters) and is sent as three connected SMS’s.
Special characters include any not listed here:
@£$¥èéùìòÇØøÅå_^{}\[~]| ÆæßÉ!"#¤%&'()*+,-./0-9:;<=>?A-ZÄÖÑܧ¿a-zäöñüà
| SMS without special characters | SMS with special characters | ||
|---|---|---|---|
| Maximum characters | Number of SMS's | Maximum characters | Number of SMS's |
| 160 | 1 | 70 | 1 |
| 306 | 2 | 134 | 2 |
| 459 | 3 | 200 | 3 |
Types of SMS Messages
The gate makes it possible to send two types of messages: ECO and PRO.
ECO messages sent from a random nine-digit number.
PRO messages are sent with a text signature or sender name. This sender name cannot contain more than 11 non-special characters. To use PRO messages, you must announce the signature.
Using SMS messages requires an additional contract, which contains prices for messages of both types.
Sending SMS Messages
Call: POST /rest/sms
Data in POST:
| Parameter | Required | Comments | Description |
|---|---|---|---|
| gsm | Required | Phone number | In format +48XXXXXXXXXXX or XXXXXXXXXXX |
| text | Required | Message subject | |
| from | Optional | The SMS Signature | |
| single | Optional | The sending of single SMS | |
| messageId | Optional | Message ID | String not exceeding 42 characters. It will be returned together with the delivery report |
Sample request (made using the Curl library):
curl -v -H "X-Rest-ApiKey:APIKEY" -H "X-Rest-ApiSign:APISIGN" -H "Content-Type:application/json" https://api.freshmail.com/rest/sms -d '{"gsm":"phoneNumber","text":"Example SMS message","messageId":432523,"from":"Recepcja"}'Correct answer:
{"status":"OK"}Wrong answer:
{
"status":"ERROR",
"errors":[
{
"message":"SMS inscription (from) doesn't exist",
"code":1105
}
]
}
Error codes:
| 1101 | Error in GSM number |
|---|---|
| 1102 | SMS content missing |
| 1103 | SMS content too long (SMS without special characters) |
| 1104 | SMS content too long (SMS with special characters) |
| 1105 | Sender name error |
| 1106 | Unconfirmed sender name (awaiting verification) |
| 1107 | Error in coding of command |
| 1108 | SMS content too long (SMS without special characters with single=1 option) |
| 1109 | SMS content too long (SMS with special characters with single=1 option) |
| 1150 | SMS not sent, awaiting final contract |
sms/sendmms
Sends an MMS message.
| Parameter | Required | Comments | Description |
|---|---|---|---|
| gsm | Required | Phone number | In format +48XXXXXXXXXXX or XXXXXXXXXXX |
| subject | Required | Message subject | String not exceeding 30 characters |
| image | Required | Image sent in MMS message | String representing an absolute URL to an image |
| messageId | Optional | Message ID | String not exceeding 42 characters. It will be returned together with the delivery report |
Sample request (made using the Curl library):
curl -v -H "X-Rest-ApiKey:APIKEY" -H "X-Rest-ApiSign:APISIGN" -H "Content-Type:application/json" https://api.freshmail.com/rest/sms/sendmms -d '{"gsm":"phoneNumber","subject":"Example MMS message","messageId":432523,"image":"http://d2651x052v6uoq.cloudfront.net/media/sass/images/logo.png"}'
Correct answer:
{"status":"OK"}Wrong answer:
{
"status":"ERROR",
"errors":[
{
"message":"Subject of MMS message too long, limit 30 characters",
"code":1110
}
]
}
| 1101 | Error in GSM number |
|---|---|
| 1102 | The subject of the MMS message is empty |
| 1110 | The subject of the MMS message is too long |
| 1150 | SMS will not be sent, contract must be signed |
Downloading message delivery report
sms/reports
SMS/MMS reports.
| Parameter | Required | Comments | Description |
|---|---|---|---|
| startDate | Optional | Date from which reports will be downloaded | In format YYYY-MM-DD HH:ii:ss or YYYY-MM-DD |
| endDate | Optional | Date from which reports will be downloaded | In format YYYY-MM-DD HH:ii:ss or YYYY-MM-DD |
| page | Optional | The page with the results you wish to download, always download page 1 by default |
Sample request (made using the Curl library):
curl -v -H "X-Rest-ApiKey:APIKEY" -H "X-Rest-ApiSign:APISIGN" -H "Content-Type:application/json" https://api.freshmail.com/rest/sms/reports -d '{"startDate":"2015-12-17","endDate":"2015-12-18"}'
Correct answer:
{
"status":"OK",
"data":[
{
"send_date":"2015-12-17 13:21:42",
"gsm":"+48555666777",
"from":"",
"type":"eco",
"message_id":"myCustomId-423657",
"modification_date":"2015-12-17 13:24:13",
"status":"DELIVERED",
"responses":[]
},
{
"send_date":"2015-12-17 13:27:21",
"gsm":"666777888",
"from":"2way",
"type":"2way",
"message_id":"myCustomId-54321345",
"modification_date":"2015-12-17 13:28:01",
"status":"DELIVERED",
"responses":[
{
"text":"Great response",
"time":"2015-12-30 07:48:33"
},
{
"text":"My another response",
"time":"2015-12-30 08:34:41"
}
]
},
{
"send_date":"2015-12-17 13:27:29",
"gsm":"777888999",
"from":"Recepcja",
"type":"pro",
"message_id":"myCustomId-3245154",
"modification_date":"2015-12-17 13:28:02",
"status":"SENT",
"responses":[]
},
{
"send_date":"2015-12-17 13:29:01",
"gsm":"",
"from":"Recepcja",
"type":"pro",
"message_id":"myCustomId-3245154",
"modification_date":"2015-12-17 13:29:01",
"status":"ERROR",
"error":"INVALID_PHONE_NUMBER",
"responses":[]
},
{
"send_date":"2015-12-18 09:01:01",
"gsm":"888999000",
"from":"",
"type":"mms",
"message_id":"myCustomId-41532",
"modification_date":"2015-12-18 09:01:55",
"status":"DELIVERED",
"responses":[]
}
],
"resultCounts":5,
"allData":1
}
Fields included in the response
| Parameter | Description |
|---|---|
| data | Contains all data on the SMS messages sent within a given period |
| resultCounts | Number of returned records in the date field |
| allData | Have all records from the particular the period been returned. The returned data limit is 1000 records. If more records are found in the response, the first 1000 is returned, while the other data should be downloaded using the page parameter |
Możliwe statusy wiadomości SMS/MMS:
| Parameter | Description |
|---|---|
| NOT_FOUND | Invalid ID number of the report expired |
| EXPIRED | Message undelivered as the number was unavailable for too long |
| SENT | The message was sent but the operator has not yet returned the delivery report |
| DELIVERED | The message has reached the subscriber |
| UNDELIVERED | Message undelivered (e.g. invalid number, unavailable number) |
| FAILED | Error during message sending - please report |
| REJECTED | Message undelivered (e.g. invalid number, unavailable number) |
| UNKNOWN | No delivery report for the message (message delivered or not possible to deliver) |
| QUEUE | Messages in the dispatcher queue |
| ACCEPTED | Message accepted by the operator |
| RENEWAL | A call attempt was not answered, another attempt will be made. |
| STOP | The sending of the message was stopped |
| ERROR | Message has not been sent |
If the SMS was not sent (i.e. the message status is ERROR), the reason for not sending the message will display in the additional error parameter. Below are potential message sending error codes:
| Parameter | Description |
|---|---|
| INVALID_PHONE_NUMBER | Invalid phone number or no phone number |
| WRONG_SENDER_NAME | Invalid sender's name (most likely the signature was not reported) |
| UNKNOWN_ERROR | Message not sent, internal operator error |
Pole modification_date:
This field lists the time of the last modification of the STATUS field.
Reply to type 2WAY messages