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:

email 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:

email 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:

email Required Subscriber email address
list Required Hash list of subscribers

Returned Data:

email 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:

email 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:

email 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:

email 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:

email 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