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