API systemu FreshMail zostało zrealizowane według wzorca REST. Komunikacja polega na wysłaniu żądania HTTP pod adres https://api.freshmail.com/rest/ i ewentualnym przesłaniu wymaganych danych. Odpowiedź jest zwracana w formacie JSON.

Uwierzytelnienie

Każde wysłane żądanie po API wymaga uwierzytelnienia. Uwierzytelnienie następuje poprzez wysłanie nagłówków HTTP o nazwach:

X-Rest-ApiKey	zawiera unikalny klucz dostępu do API, każdy z klientów posiada swój unikalny klucz API.
X-Rest-ApiSign	zawiera podpis żądania. Podpis jest generowany na podstawie parametrów wysyłanych w żądaniu oraz na podstawie ApiSecre

Istnieją dwa schematy generowania X-Rest-ApiSign, oba zostały przedstawione poniżej:

Schemat oparty na URL-encoded query

wymagane jest dodanie nagłówka Content-Type w żądaniu http o wartości:

text/html lub application/xml lub text/json, np.:

Content-Type: text/json

wtedy można wygenerować X-Rest-ApiSign w oparciu o algorytm:

sha1( ApiKey + GET_data + POST_data + ApiSecret )

Opcje konfiguracji

ApiKey	32 znakowy Api key.
GET_data	pełna ścieżka dostępu – np. /rest/ping, /rest/mail itp. Więcej szczegółów w sekcji Ścieżka dostępu.
POST_data	dane POST umieszczone w żądaniu. Jeśli w żądaniu znajdują się tylko dane GET to wartość POST_data jest pusta. Wartości muszą być escapowane na potrzeby URL, np.:
ApiSecret	znaków, unikalny sekret dla każdego z klientów. W przypadku skompromitowania klucza należy bezzwłocznie wygenerować nowy

Schemat oparty na JSON

Jeśli zapytanie powiedzie się wtedy pod kluczem „status” będziemy mieli wartość 'OK'.

Jeśli metoda ma zwrócić dane będą one pod kluczem „data”.

Natomiast jeśli wystąpi błąd pod kluczem „status” będzie wartość „ERROR”, a pod kluczem „errors” znajdzie się opis błędów jakie wystąpiły wraz z kodami błędów. W przypadku błędu kod HTTP zwracany w nagłówku jest adekwatny do zaistniałego błędu, czyli np. 404, 403 itp. W przypadku braku błędu kod HTTP to 200.