Description of API

When starting your work with FreshMail API, it’s worth using ready wrappers and samples.

FreshMail API was executed according to REST standard. Communication consists of sending HTTP request to https://api.freshmail.com/rest/ and transferring required data. Response is sent in JSON format.

Authentication

Every request sent to API requires authentication. Authentication is executed by sending HTTP headers named:

X-Rest-ApiKey includes unique access key to API; each client has his own unique API key. subscriptions → subscription list → API and advanced options
X-Rest-ApiSign Includes request signature. Signature is generated according to parameters sent in the request on the basis of ApiSecret.

Two X-Rest-ApiSign generation schemes are available. Both are shown below:

Scheme based on URL-encoded query:

adding Content-Type headline is required in http request with the value of:

text/html lub application/xml lub application/json, e.g.:
Content-Type: application/json

then the following can be generated X-Rest-ApiSign according to the algorithm:

sha1( ApiKey + GET_data + POST_data + ApiSecret )

where:

ApiKey Api key with 32 characters.
GET_data full access path – e.g.. /rest/ping, /rest/mail etc. More details in „Access path” section.
POST_data POST data included in a request. If a request includes only GET data, POST_data value is empty. Values must be escaped for URL purposes, e.g.: email=test%40test.pl&subject=test+email
ApiSecret 40 characters, unique secret for each client.
In case of key is compromised, a new one should be generated immediately.

2. Scheme basing on JSON:

adding Content-Type headline is required in http request in the following form:

Content-Type: application/json

X-Rest-ApiSign according to the algorithm:

sha1( ApiKey + GET_data + JSON_data + ApiSecret )

where:

ApiKey Api key with 32 characters.
GET_data full access path – e.g. /rest/ping, /rest/mail etc. More details in „Access path” section.
JSON_data JSON data included in a request. If a request includes only GET data, JSON_data value is empty. Example of JSON_data: {"subscriber":"test@test.pl"}
ApiSecret 40 characters, unique secret for each client.In case of key is compromised, a new one should be generated immediately.

API responses

Response for each request sent to API is in JSON format, e.g.

{"status":"OK","data":[1,2,3]}

If the enquiry succeeds, the "OK" value will be under the "status" key. If the method is to return data, they will be under the "data" key, whereas if error occurs, the "ERROR" value will be under "status" key and the "errors" key will include a description and codes of errors. In case of error, a HTTP code which is returned in the headline is adequate to the error, that is, e.g. 404, 403 etc. In case of no error, HTTP code is 200.

Error management

In case of an error, response state is "ERROR", whereas "errors" field includes text description and code of error, e.g.:

                {"errors":[
                           {"message":"Subject line missing",
                           "code": 1202}
                       ],
               "status":"ERROR"}

lub

               {"errors":[
                          {"message": "Incorrect From address",
                            "code": 1201},
                          {"message": "Email subject missing",
                            "code": 1202}
                         ],
                "status":"ERROR"}

 Access path

Each action which can be executed has its unique access path which looks as follows:

/rest/[Controller]/[Action]/[param]/[param]/[param]

Controller controller name, e.g. ping, mail, etc.
Action action name within a controller.
param parameter, cannot include „/”; in most cases, additional GET parameters are unnecessary. In case it is required, its number and format is defined in a description of action.

General error codes

500 Server error (Internal Server Error).
1000 No authorization.
1001 Controller/action not found.
1002 Unsupported protocol. Please use https protocol.
1003 Unsupported type of request, e.g. GET was sent, POST was expected.
1004 No authorization to recall particular controller/action.