REST API documentation
Subscribers – managing subscribers
The controller can be used to add and update subscriber data on subscriber lists.
Subscriber status codes
Description | Value | Explanation |
Active | 1 | Subscriber active, campaign may be sent |
Awaiting activation | 2 | Subscriber must click on activation link before being added to active list |
Inactive | 3 | Subscriber did not click on activation link in confirmation mail before expiration |
Resigned | 4 | Subscriber resigned from mailing list |
Soft bounce | 5 | Message bounced several times in a row from subscriber inbox (soft) with code (http://www.ietf.org/rfc/rfc1893.txt) |
Hard bounce | 8 | Message bounced several times in a row from subscriber inbox (hard) with code (http://www.ietf.org/rfc/rfc1893.txt) |
Adding subscribers
New subscribers can be added to a list or current subscribers can have their statuses changed.
Call: POST /rest/subscriber/add
Data in POST:
Required | Email address of subscriber | |
list | Required | Hash of subscriber list |
state | Optional | Status to be added to subscriber, “awaiting activation” by default |
confirm | Optional | If subscriber is to be send confirmation mail or not. Possible valued 0 or 1. With confirmation by default. Field is ignored (email not sent) if subscriber given any other status besides “Awaiting activation”. |
custom_fields | Optional | Table with additional fields and additional values in the form of {"tag personalisation field 1":"value", "tag personalisation field 2":"value"} |
Error codes:
1301 | Email address error |
1302 | Subscriber list does not exist |
1303 | One or more additional fields contains an error |
1304 | Subscriber already exists on this list and has Active or Awaiting Activation status |
1305 | Attempted addition of improper subscriber status |
Modifying subscriber data
Method of updating subscriber status and data
Call: POST /rest/subscriber/edit
Data in POST:
Required | Subscriber email address | |
list | Required | Subscription hash list |
state | Optional | Status to be added to subscriber, default is no changes |
custom_fields | Optional | Table with additional fields and values in format: {"tag personalised field 1":"value", "tag personalised field 2":"value"} |
Error codes:
1331 | Subscriber doesn’t exist |
1302 | Subscriber list or hash list doesn’t exist |
1305 | Attempt to add incorrect subscriber status |
Downloading subscriber data
Call: GET /rest/subscriber/get/[list]/[email]
Data in GET:
Required | Subscriber email address | |
list | Required | Hash list of subscribers |
Returned Data:
Subscriber email address | |
state | Subscriber status |
custom_fields | Number of subscribers sent to |
sent | Date of sent campaigns in format: yyyy-mm-dd hh:ii:ss |
Error codes:
1311 | Error in email address |
1312 | Subscriber list doesn’t exist |
Deleting subscribers
Removing subscribers from subscriber lists
Call: POST /rest/subscriber/delete
Data in POST:
Required | Subscriber email address | |
list | Required | Hash list of subscribers |
Error codes:
1321 | Address does not exist on this subscriber list |
1322 | Subscriber list or hash doesn’t exist |
Download subscriber action history
How to download subscriber action history.
To execute this action:
POST /rest/subscriber/getHistory
Data in POST:
required | Subscriber email address | ||
list | required | Subscriber list hash | |
limit | optional | Number of subscriber actions to download (default 10) |
Sample request:
{"email":"tester1@freshmail.com"
"list":"4zcnmd2ski"
"limit":"30"}
Received data:
name | Name of campaign | |
---|---|---|
email_topic | Subject of campaign | |
scheduled_sent | Date and time of sent campaign (in yyyy-mm-dd and hh-ii-ss format) | |
state | Subscriber status - deliveries, soft bounces, hard bounces | |
opens_count | Number of subscriber opens | |
clicks_count | Number of subscriber clicks |
Error codes:
1311 | Incorrect email address | |
---|---|---|
1312 | Subscriber list does not exist | |
1313 | Subscriber does not exist on given subscriber list | |
1314 | Attribute value limit is incorrect | |
1315 | Subscriber does not have an action |
Example of incorrect reply:
{"status":"ERROR",
"errors":[{
"message":"Subscriber doesn't exist",
"code":1313 }]}
Example of correct reply:
{"status":"OK", "data":[{ "name":"4 campaign sent on 30.07.2013", "email_topic":"Autumn promotion", "scheduled_sent":"2013-07-30 21:37:42", "state":"DELIVERED", "opens_count":"1", "clicks_count":"2" }]}
Downloading subscriber action history
Process for downloading recent subscriber actions.
Call: POST /rest/subscriber/getHistory
Data in POST:
Required | Subscriber email address | |
list | Required | Hash list of subscribers |
limit | Optional | Number of downloaded subscriber actions (default is 10) |
Example request:
{
"email":"tester1@freshmail.com"
"list":"4zcnmd2ski"
"limit":"30"
}
Returned Data:
name | Campaign name |
email_topic | Campaign subject |
scheduled_sent | Date and time of campaign (format: yyyy-mm-dd hh:ii:ss) |
state | Subscriber status (delivery, hard & soft bounces) |
opens_count | Number of opens by subscriber |
clicks_count | Number of clicks by subscriber |
Error codes:
1311 | Error in email address |
1312 | Subscriber list doesn’t exist |
1313 | Subscriber doesn’t exist on given list |
1314 | Value attribute limit is in incorrect |
1315 | Subscriber has no actions |
Sample incorrect reply:
{"status":"ERROR",
"errors":[{
"message":"Subscriber doesn't exist",
"code":1313
}]}
Sample correct reply:
{"status":"OK",
"data":[{
"name":"4 tuesday campaign 30.07.2013",
"email_topic":"Summer promotion",
"scheduled_sent":"2013-07-30 21:37:42",
"state":"DELIVERED",
"opens_count":"1",
"clicks_count":"2"
}]}
Spamtests
The controller can be used to check emails for content likely to be labeled as spam.
Checking for consistency with SpamAssassin filters
Messages are examined for spam points and the grade likely to be assigned by SpamAssassin.
Remember: Not all email service providers use this programming, results are subjective and the configurations of other programs may produce different results. Passing results on one test do not guarantee similar results on another.
Call: /rest/spam_test/check
Data:
subject | Required | Email subject |
from | Optional | Sender address |
from_name | Optional | Sender name |
html | Optional *) | HTML content |
text | Optional *) | Text content |
*) At least one field must be completed
Returned Data:
tests | List of antispam tests not applied |
score | Summary of assigned spam points |
Error codes:
1901 | No subject |
1902 | Incorrect “from” address |
1904 | No mail content |
1906 | Error in verification system |
1907 | Maximum number of daily tests exceeded |
Creating accounts
Both primary and sub user accounts can be created.
Call: POST /rest/account/create
Data in POST:
login | Required | Login for new user (email address) |
password | Required | New user password |
firstname | Required | User first name |
lastname | Required | User last name |
company | Optional | Company name |
phone | Required | Telephone number |
activation_mail | Optional | Activation sent or not (default is yes) |
activation | Optional | Activation required or not (default is yes) |
child_account | Optional | Is account primary or sub (default sub) |
Returned Data:
hash | New account hash |
api_key | New account Api key |
api_secret | New account Secret |
Error codes:
1501 | No email address / login |
1502 | Incorrect login |
1503 | Already logged in |
1504 | No password |
1505 | Password too weak - must contain 8 characters including one capital letter and one special character |
1506 | First name missing |
1507 | Last name missing |
1509 | Telephone number missing |
1510 | An error occurred while creating account |
1511 | Account was not created |
1512 | Account was not saved in application |
1513 | No permission to create account |
Subscribers – managing many subscribers within one request
The same commands used to manage individual subscribers can be used to manage groups of up to 100 subscribers at a time.
Adding groups of subscribers
It is possible to add multiple subscribers to lists or update their statuses to “Active” or “Awaiting Activation”. If only part of the addresses are added (if, for example, an address in incorrect), code 200 will be returned along with data connected with the incorrect addresses.
Call: POST /rest/subscriber/addMultiple
Data in POST:
subscribers | Required | Table with email addresses and additional fields in the form of{"email" : "adres_email", "custom_fields": { "tag personalisation field 1" : "value", "tag personalisation field 1" : "value" } } ”custom_fields” is not obligatory |
list | Required | Subscribers has list |
state | Optional | Status to be added to subscribers, “Awaiting activation” by default. |
confirm | Optional | If confirmation mail should be sent or not. Possible values are 0 and 1. Confirmation mail sent by default. Field is ignored (mail not sent) if subscriber status is other than “Awaiting activation”. |
Sample request:
{"list":"id_hash",
"subscribers" : [ {"email":"tester1@freshmail.com",
"custom_fields":{"name":"Hanna",
"promotion_code":"abcde"} },
{"email":"tester2@freshmail.com",
"custom_fields":{"name":"Anna",
"promotion_code":"efgh"} },
{"email":"tester3@freshmail.com",
"custom_fields":{"name":"Maria",
"promotion_code":"wxyz"} } ] }
Error codes:
1331 | Adding/updating subscriber failed |
1332 | Subscriber list or hash doesn’t exist |
1335 | Attempt to add incorrect subscriber status |
1336 | No email given to add |
1399 | Too many subscribers in one command - limit 100 |
Sample of frequent error, sent request:
{"list":"4zcnmd2ski",
"subscribers":[{"email":"correct@address.email.com"},
{"email":"incorrect email addressl"}]}
Returned Data (answer code 200):
{"status":"OK",
"data":{
"inserted":1,
"not_inserted":1,
"Errors":[{"email":"incorrect email address",
"error":"Email address not correct",
"code":1301}]}}
Error codes returned for particular subscribers are identical to the error codes for /rest/subscriber/add
Modifying data for groups of subscribers
Updating and modification for multiple subscribers at once
Call: POST /rest/subscriber/editMultiple
Data in POST:
subscribers | Required | Table with email address and additional fields in the form of{"email" : "adres_emaiil", "custom_fields": { "tag personalisation field 1" : "value", "tag personalisation field 1" : "value" } } ”custom_fields” is not obligatory |
list | Required | Subscriber hash list |
state | Optional | Status to be added to subscriber, no change by default |
Error codes:
1331 | Adding/updating subscribers failed |
1332 | Subscriber list or hash list doesn’t exist |
1335 | Attempt to add incorrect subscriber status |
1336 | No addresses given to update |
1399 | Too many subscribers in one command - limit 100 |
Returned Data/information about errors are identical to those used in /rest/subscriber/addMultiple
Modifying additional fields for all subscribers
Updating selected additional fields and setting values for all subscribers
Call: POST /rest/subscriber/updateFieldValue
Data in POST:
listHash | Required | Subscriber hash list |
tag | Required | Tag for additional field (ex. Promotional code) |
value | Required | Value for additional field for all subsribers |
url | Required | Online address to which replies are to be sent after updating |
Returned Data:
id | Process Id |
Error codes:
1381 | Additional field does not exist |
1382 | No hash list or tag for additional field |
1383 | Incorrect URL address |
1384 | Too many characters in “value” field - max. 255 |
1385 | “Value” field is required |
1386 | Updating process for field is in progress, wait until finished |
Sample error response:
{"status":"ERROR",
"errors":[{
"message":"Incorrect URL address",
"code":1383
}]}
Sample proper response (answer code 200):
{"status":"OK",
"data":{
"id":5
}}
After updating, the command will be sent to the provided URL. The response will be in the POST format, and the command will contain the following data:
id | Id of process |
updated | Number of updated subscriber fields |
Sample commands:
{"status":"OK",
"data":{
"id":5,
"updated":150
}}
Code with status “OK” is expected after script:
{"status":"OK"}
If the response is incorrect, the script will continue to attempt to communicate but will stop with more errors.
Downloading data from multiple subscribers
If a request is partially incorrect (ex. Email address does not exist) or is completely incorrect (ex. None of the email addresses exist), code 200 will be returned along with data from the incorrect addresses.
Call: POST /rest/subscriber/getMultiple
Data in GET:
subscribers | Required | Table with user email addresses:[{"email":"tester1@freshmail.com"}, {"email":"tester2@freshmail.com"}, {"email":"tester3@freshmail.com"} ] |
list | Required | Subscriber hash list |
Returned Data:
Subscriber email address | |
state | Subscriber status |
custom_fields | Additional fields with values |
errors | Table with errors (in cases where certain addresses don’t exist) |
Error codes:
1341 | Subscriber list does not exist |
1342 | Table with subscribers is empty |
1399 | Too many subscribers in command - limit 100 |
Mass deletion of subscribers
Deleting groups of subscribers from lists
Call: POST /rest/subscriber/deleteMultiple
Data in POST:
subscribers | Required | Table with user email addresses:
[ {"email":"tester1@freshmailcoml"}, {"email":"tester2@freshmail.com"}, {"email":"tester3@freshmail.com”} ] |
list | Required | Subscriber hash list |
Error codes:
1351 | Subscriber list doesn’t exist |
1352 | Subscriber lists don’t exist / have been deleted |
1399 | Too many subscribers in one command - limit 100 |
Returned data/Information about errors is identical to process for /rest/subscriber/addMultiple
Adding subscribers to list of blocked recipients
Added subscriber addresses to lists of blocked recipients.
Call: POST /rest/subscriber/addBlocks
Data in POST:
emails | Required | Table with user email addresses:
{ "emails":[ "tester1@freshmail.com", "tester2@freshmail.com", "tester3@freshmail.com" ] } |
Returned Data:
stats['added'] | Number of added subscribers |
stats['existing'] | Number of existing subscribers |
stats['incorrect'] | Number of incorrect addresses |
Incorrect_mails | Table with incorrect addresses |
Error codes:
1301 | Recipient addresses are incorrect |
1336 | Recipient addresses not supplied |
1343 | Format of submitted data is incorrect |
Deleting subscribers from blocked recipient lists
Removing subscribers from lists of blocked recipients. This is possible only with addresses you have blocked yourself.
Call: POST /rest/subscriber/removeBlocks
Data in POST:
emails | Required | Table of user email addresses:
{ "emails":[ "tester1@freshmail.com", "tester2@freshmail.com", "tester3@freshmail.com" ]} |
Returned Data:
stats['removed'] | Number of deleted subscribers |
stats['not_existing'] | Number of non-existent subscribers |
stats['incorrect'] | Number of incorrect subscribers |
Error codes:
1336 | Addresses to add not supplied |
1343 | Supplied format is incorrect |
Creating a new campaign
The controller can be used to create, check and send campaigns.
Call: POST /rest/campaigns/create
Data in POST:
name | Required | Campaign name |
---|---|---|
url | Optional | Address of HTML page |
html | Required* | HTML content in email (required if there is no text content) |
text | Required* | Text content in email (required if there is no HTML content) |
subject | Optional | The subject of the email to be sent through the system. If there is no subject then the name of the campaign will be used. |
from_address | Optional | The “from” field - if left empty, the sender address from the system will be used by default. |
from_name | Optional | The “sender” field - if left empty, the sender name from the system will be used by default. |
reply_to | Optional | The “reply to” field - if left empty, the sender address from the system will be used by default. |
list | Required * | Hash subscription lists that campaign should be sent to. Lists can be in table form if campaign is for multiple lists. |
group | Required * | Hash groups that campaign should be sent to. Groups can be in table form if campaign is for multiple groups. |
resignlink | Optional | URL address to which subscribers who want to resign are directed to. |
Returned data:
hash | A properly created campaign will be assigned a hash. |
---|
Error codes:
1701 | No campaign name |
---|---|
1702 | No content |
1703 | Error in URL address |
1704 | Client error (internal) |
1705 | No parameters (internal) |
1706 | Error in sender address (from_address) |
1707 | Error in “reply to” address |
1708 | No subscribers lists or groups |
1709 | At least one hash has an error |
1710 | At least one hash group has an error |
1711 | Nothing found for hash given |
1712 | No group found for hash given |
1713 | Resignation link not in proper URL format. |
Subscriber lists – management
Controlled is used for management of subscriber lists. It enables adding, listing and deleting such lists..
Creating lists
Function is used for subscriber lists. It returns a hash which can be further used.
Recall:
/rest/subscribers_list/create
Data:
name | Required | Name of subscriber list | |
---|---|---|---|
description | Optional | Description of subscriber list | |
custom_fields | Optional | Table defining custom fields (according to a description from Creating custom fields on lists) |
Returned data:
hash | Hash of a new subscriber list | |
---|---|---|
custom_fields | Table with full description of created fields - it they were t be created. |
Error codes:
1601 | Empty value in name field | |
---|---|---|
1602 | Failed to create subscriber list | |
1603 | Incorrect list of custom fields. | |
1604 | Personalization tag should consist of only letters, digits and underscore. | |
1605 | Incorrect field type. |
Modifying lists
Function is used for modification of subscriber lists.
Recall:
/rest/subscribers_list/update
Data:
hash | Required | Hash of subscription list | |
---|---|---|---|
name | Required | Name of subscription list | |
description | Optional | Description of subscription list |
Error codes:
1611 | Empty value in name field or no parameter | |
---|---|---|
1604 | No rights to this list |
Deleting lists
Function is used for deleting subscriber lists.
Recall:
/rest/subscribers_list/delete
Data:
hash | Required | Hash of subscriber list |
---|
Error codes:
1604 | No rights for this list | |
---|---|---|
1605 | Failed to delete subscriber list |
Downloading data concerning lists
Function is used for listing all subscriber lists. It returns tables with data concerning all lists which the account is authorized to.
Recall:
/rest/subscribers_list/lists
Returned data:
hash | Hash of subscriber list | |
---|---|---|
name | Name of subscriber list | |
description | Description of subscriber list | |
creation_date | Subscriber list creation date | |
subscribers_number | Number of current subscribers |
Creating custom fields on lists
Function is used for creating custom fields on subscriber lists.
Recall:
/rest/subscribers_list/addField
Data:
hash | Required | Hash of subscription list | |
---|---|---|---|
name | Required | Field name on the list | |
tag | Optiona | Tag under which the values from this field will be available in e-mails (in case of no such tag, it will be created according to a name of the field) | |
type | Optional | Field type – 0 text, 1 numerical (default: text) |
Returned data:
id_hash | Hash of custom field | |
---|---|---|
field_name | Name of custom field | |
personalization_tag | Tag under which the values from this field will be available in e-mails | |
field_type | Field type – 0 text, 1 numerical (default: text) |
Error codes:
1622 | Incorrect or empty hash of subscriber list | |
---|---|---|
1623 | Incorrect or empty field name | |
1624 | Incorrect tag name | |
1625 | Incorrect field type | |
1626 | Custom field with this tag already exists |
Displaying a list of custom fields on a particular list
Function is used for displaying all custom fields on a selected subscriber list.
Recall:
/rest/subscribers_list/getFields
Date:
hash | Required | Hash of custom field |
---|
Returned data:
hash | Hash of custom field | |
---|---|---|
name | Name of custom field | |
tag | Tag under which the values from this field will be available in e-mails |
Error codes:
1632 |
Incorrect or empty hash of subscriber list |
---|
Campaigns – operating a campaign
Sending campaigns
Call: POST /rest/campaigns/edit
Data in POST:
id_hash | Required | Hash of campaign to be edited |
---|---|---|
name | Optional | Campaign name |
url | Optional | Address from which HTML code should be downloaded |
html | Optional | HTML content of email |
text | Optional | Text content of email |
subject | Optional | Subject of email to be sent. Campaign name used by default. |
from_address | Optional | “From” field, system address used by default. |
from_name | Optional | “Sender” field, system name used by default. |
reply_to | Optional | “Reply to” field, system address used by default. |
list | Optional | Subscriber hash lists to which campaign should be sent. Can be in the form of a table if campaign is sent to more than one list. |
group | Optional | Hash group to which campaign should be sent. Can be in the form of a table if campaign is sent to more than one list. |
resignlink | Optional | URL address to which resignation requests should be directed. |
Error codes:
1750 | No campaign to edit under given hash |
---|---|
1751 | Campaign already sent, modification not possible |
Other error codes are the same as in the campaign creation process.
Deleting campaigns
Call: POST /rest/campaigns/delete
Data in POST:
hash | Required | Hash of campaign to be deleted |
---|
Error codes::
1724 | No campaign with given hash |
---|---|
1798 | Campaign has already been deleted |
Sending text campaigns
Call: POST /rest/campaigns/sendTest
Data in POST:
hash | Required | Hash of campaign to be sent |
---|---|---|
emails | Required | Address or table of addresses to be sent |
custom_fields | Optional | Table of additional fields, default is random data from subscriber list |
Sample commands:
{"hash":"campaign_hash",
"emails":"test@test.com",
"custom_fields":{
"name":"John",
"surname":"Down"}}
or
{"hash":"hash_campaign",
"emails":["test1@test.com","test2@test.com"]}
Error codes::
1721 | No hash or hash in wrong format |
---|---|
1722 | No email address |
1723 | Error in at least one address |
1724 | Campaign with given hash doesn’t exist |
1725 | Campaign not ready for testing |
1726 | Sending failed |
Sending campaigns
Call: POST /rest/campaigns/send
Data in POST:
hash | Required | Hash of campaign to be sent |
---|---|---|
time | Optional | Date of campaign sending in format YYYY-MM-DD H:i:s |
Error codes::
1731 | No hash or hash is in incorrect format |
---|---|
1732 | Sending time is incorrect |
1733 | Sending time cannot be earlier than present time |
1734 | No campaign with given hash |
1735 | Campaign not ready for testing |
1736 | Campaign already finalised for sending or in process of being sent |
Reports – reports from a campaign
The controller can be used to download reports and lists of sent campaigns.
Downloading lists of sent campaigns
Call: GET /rest/reports/campaignsList/[page]
Data in GET:
page | Optional | Page of campaign reports, default is first page |
---|
In response to the command, the server will send a list of 25 campaigns. Sent data includes:
name | Campaign name |
---|---|
topic | E-mail subject in campaign |
subscribers | Number of subscribers sent to |
id_hash | Unique campaign identification |
sent | Date of sent campaigns, in format: yyyy-mm-dd hh:ii:ss |
Downloading aggregate campaign reports
Call: GET /rest/reports/campaign/[id_hash]
Data w GET:
id_hash | Required | Unique campaign identifications, available by calling method/rest/reports/campaignslist |
---|
Returned data:
subscribers | Number of subscribers who received a campaign |
---|---|
delivered | Number of delivered messages |
hard_bounce | Number of hard bounces (http://www.ietf.org/rfc/rfc1893.txt) |
soft_bounce | Number of soft bounces (http://www.ietf.org/rfc/rfc1893.txt) |
opened | Number of opened messages |
clicked | Number of clicked links |
unique_opened | Number of unique opens |
unique_clicked | Number of unique clicks |
resigned | Number of subscriber resigns |
Downloading subscriber behaviour reports
Call: GET /rest/reports/campaignTimeDetails/[id_hash]
Data w GET:
id_hash | Required | Unique identifiers for campaigns can be obtained by calling for method/rest/reports/campaigns list |
---|
Returned Data – table with subsequent subscriber actions:
{"status":"OK","data":
[
{"opened":"4",
"unique_opened":"4",
"clicked":"3",
"unique_clicked":"1",
"time":"2012-03-26 16:50"},
{"opened":"1",
"unique_opened":"1",
"clicked":"1",
"unique_clicked":"1",
"time":"2012-03-27 08:30"}
]
}
opened | Number of opens in a given time period |
---|---|
clicked | Number of clicks in a given time period |
unique_opened | Number of unique opens in a given time period |
sunique_clicked | Number of unique clicks in a given time period |
time | Time in the format of “yyyy-mm-dd HH:ii”, in ten minute intervals |
Error codes:
1401 | Incorrect page number |
---|---|
1402 | Campaign with given id__hash does not exist |
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
}
]
}
Error codes:
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
Transaction e-mails – sending individual e-mails
The controller can be used to send individual transactional mails. The default of all parameters should be set in UTF-8 coding. They can be changed using the encoding parameters.
Call: POST /rest/mail
Data in POST:
subscriber | Required | Address of recipient of mail being sent |
---|---|---|
subject | Required | Email subject |
html | Required* | HTML content of mail |
text | Required* | Text content of mail |
from | Optional | “From” field - default will appear if left empty |
from_name | Optional | “From name” field - default will appear if left empty |
reply_to | Optional | “Reply to” field - default will appear if left empty |
encoding | Optional | Coding to appear in sent mail. The default is UTF-8. Remember that mail must be delivered in same encoding as that identified in parameters Supported codes are: UTF-8, iso-8859-2 |
attachments | Optional | Link to attachments to mail. Maximum size is 0.5 MB |
tracking | Optional | Value field is 0/1. Select 1 to enable behavioural tracking codes Note: This means that the domain in which the links appear will be changed and the HTML image will be added to the tracking image. |
domain | Optional | Domains for rebranding, active values only if mail tracking is activated. If value is empty default will be activated. |
tag | Optional | Tag according to type of mail. Tags cause transactional mails to be divided into groups. Sample tags: Reminder mails, confirmation mails, etc. |
Error codes:
1201 | Error in subscriber address |
---|---|
1202 | No email subject |
1203 | No HTML or text content |
1204 | Error in “reply to” address |
1205 | Error in sender address |
1206 | Sender name cannot be empty |
1207 | Daily limit of mails exceeded |
1208 | Unsupported coding |
1209 | Error in attachment link |
1210 | Attached file doesn’t exist |
1211 | Maximum attachment size exceeded |
1212 | Error in rebranding domain, verify if domain is activated |
1213 | Error in campaign tags (too long or includes unsupported characters) |
1250 | System error, mail not sent |
1251 | Admin block, mail not sent to particular subscriber |
Ping – testing
The controller is used to test the proper functioning of the API. GET and POST commands can be tested separately.
Calling: GET /rest/ping
In response, the server answers “pong”.
Calling: POST /rest/ping
In response, the server send data in POST.
Description of API
FreshMail’s API was created based on REST patterns. Communication is based on sending HTTP commands to https://api.freshmail.com/rest/ along with the requested data. Replies are sent in JSON format.
Authentication
Every API command sent needs authentication, which is obtained by sending HTTP headers:
X-Rest-ApiKey | Contains unique access key for API. Each client has a unique key.subscription → subscription lists → advanced options and API |
---|---|
X-Rest-ApiSign | Contains command signature which is generated on the basis of parameters sent in the command or on the basis of ApiSecret. |
There are two diagrams for generating X-Rest-ApiSign, as described below:
Diagram based on URL-encoded query:
Add Content-Type header in the http command with this value:
text/html lub application/xml lub application/json, for example:
Content-Type: application/json
An X-Rest-ApiSign can be generated this way based on the algorithm:
sha1( ApiKey + GET_data + POST_data + ApiSecret )
where:
ApiKey | 32 character Api key. |
---|---|
GET_data | Full access path - for example,. /rest/ping, /rest/mail itp. More details in “Access Path” section. |
POST_data | POST data placed in the command. If only GET data is in the command, the POST_data will be empty. Values must be escaped for the needs of the URL. For example, email=test%40test.pl&subject=test+email |
ApiSecret | 40 characters, unique secret for each client. New keys must be generated immediately in case of a compromised key. |
Diagram based on JSON:
A Content-Type header must be added in the command in the form of:
Content-Type: application/json
A X-Rest-ApiSign can then be generated on the basis of the algorithm:
sha1( ApiKey + GET_data + JSON_data + ApiSecret )
where:
ApiKey | 32 character Api key. |
---|---|
GET_data | Full access path, for example /rest/ping, /rest/mail itp. More details in„Access path” section. |
JSON_data | Data is sent in JSON format in commands. If the command contains only GET data, the JSON_data value is empty. An example JSON_data value: {"subscriber":"test@test.com"} |
ApiSecret | 40 characters, unique secret for each client. New keys must be generated immediately in case of a compromised key. |
API responses
Responses to every command sent to API are in JSON format, for example -
{"status":"OK","data":[1,2,3]}
If the query is successful, the “status” will have the value of “OK”. Returned data will be labeled as “data” and Errors are labeled as “errors”. HTTP coding errors are identified in the header as, for example, 404, 403, etc. In case of an absence or an error code, the default is 200.
Error management
In case of error, the answer status will be “ERROR”, and the “errors” field will contain a description of the error or its code:
{"errors":[
{"message":"No email subject",
"code": 1202}
],
"status":"ERROR"}
or
{"errors":[
{"message": "Address in wrong format",
"code": 1201},
{"message": "No email subject",
"code": 1202}
],
"status":"ERROR"}
Access path
Every action that can be taken has its own access path. The path is constructed in the following way:
/rest/[Controller]/[Action]/[param]/[param]/[param]
Controller | Name of the controller - ping, mail, etc. |
---|---|
Action | Name of the action within the controller |
param | Parameter cannot contain „/”, in most cases additional GET parameters are not necessary. If required, the number and format is given in the description of the action. |
General error codes
500 | Server error (Internal Server Error). |
---|---|
1000 | No authorization. |
1001 | Controller/action not found. |
1002 | Unsupported protocol. |
1003 | Unsupported command type |
1004 | No permission to request controller/action |