Szablony mailingowe klienta

Kontroler służy do pobierania danych dotyczących szablonów mailingowych klienta.

Listowanie aktywnych szablonów klienta

Metoda zwraca wszystkie aktywne szablony mailingowe klienta w formacie json.

Wywołanie:

POST /rest/templates/lists

Dane w POST:

Zwracane dane (kod odpowiedzi 200):

Zwracanie informacji o pojedynczym szablonie klienta

Metoda zwraca szczegóły dotyczące pojedynczego szablonu mailingowego klienta o podanym hashu.

Wywołanie:

POST /rest/templates/template

Dane w POST:

Zwracane dane (kod odpowiedzi 200):

Zwracane dane (kod odpowiedzi 422):

Dokumentacja API V2

Wywołanie:

POST /rest/mail

Dane w POST:

Kody błędów:

Autoryzacja

Dokumentacja PDF API REST v 1.0.34

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. Klient ma do wyboru jedną z dwóch możliwości uwierzytelnienia:

• Bearer Token
• ApiKey & ApiSign

Bearer Token (Preferowana forma autoryzacji)

Uwierzytelnienie następuje poprzez wysłanie nagłówka HTTP o nazwie:

Przykład poprawnego nagłówka:
Authorization: Bearer fisgvt.6waelw6v7WiZ68mnFMExI79YXY3Y1RH0Xc5

ApiKey & ApiSign

Uwierzytelnienie następuje poprzez wysłanie nagłówków HTTP o nazwach:

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

1. 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 application/json, np.:
Content-Type: application/json

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

sha1( ApiKey + GET_data + POST_data + ApiSecret )

gdzie:

2. Schemat oparty na JSON

wymagane jest dodanie nagłówka Content-Type w żądaniu http w postaci:

Content-Type: application/json

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

sha1( ApiKey + GET_data + JSON_data + ApiSecret )

gdzie:

Odpowiedzi API

Odpowiedź na każde żądanie wysłane do API jest w formacie JSON, np.

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

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.

Obsługa błędów

W razie wystąpienia błędu status odpowiedzi jest równy „ERROR” natomiast pole „errors” zawiera opis słowny błędu oraz kod błędu, np.

                {"errors":[
                           {"message":"Brak tematu emaila",
                           "code": 1202}
                       ],
               "status":"ERROR"}

lub

               {"errors":[
                          {"message": "Błędny adres odbiorcy",
                            "code": 1201},
                          {"message": "Brak tematu emaila",
                            "code": 1202}
                         ],
                "status":"ERROR"}

 Ścieżka dostępu

Każda z akcji jaką można wykonać ma swoją osobną ścieżkę dostępu. Ścieżka zbudowana jest w następujący sposób:

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

Ogólne kody błędów

Spamtesty

Kontroler służy do sprawdzania maili pod kątem prawdopodobieństwa wpadnięcia wiadomości do spamu.

Sprawdzenie zgodności z filtrami SpamAssassin

Medota służy do przetestowania ile punktów spamowych oraz za co dostanie Twoja wiadomość w filtrze SpamAssassin.

Pamiętaj: Nie wszystkie systemy pocztowe korzystają z tego oprogramowania, wynik jest poglądowy i przy innej konfiguracji programów pocztowych może się różnić od pokazanego w tym teście. Wynik pozytywny (poniżej 5.0 punktów spamowych NIE oznacza, że inne filtry antyspamowe nie zatrzymają twojej wiadomości).

 Wywołanie

/rest/spam_test/check

Dane:

^*) Co najmniej jedno z wyróżnionych pól musi być wypełnione 

Zwracane dane:

Kody błędów:

Listy odbiorców – zarządzanie

Kontroler służy do zarządzania listami subskrypcyjnymi. Umożliwia ich dodawanie, modyfikowanie, listowanie oraz usuwanie.

Tworzenie list

Funkcja służy do tworzenia list subskrypcyjnych. Zwraca hash listy, którym można się dalej posługiwać.

Wywołanie:

/rest/subscribers_list/create

Dane:

Zwracane dane:

Kody błędów:

Modyfikowanie list

Funkcja służy do modyfikowania list subskrypcyjnych.

Wywołanie:

/rest/subscribers_list/update

Dane:

Kody błędów:

Usuwanie list

Funkcja służy do usuwania list subskrypcyjnych.

Wywołanie:

/rest/subscribers_list/delete

Dane:

Kody błędów:

Pobieranie danych o listach

Funkcja służy do listowania wszystkich list subskrypcyjnych. Zwraca tablice z danymi wszystkich list do których konto ma uprawnienia.

Wywołanie:

/rest/subscribers_list/lists

Zwracane dane:

Tworzenie pól dodatkowych w listach

Funkcja służy do tworzenia pól dodatkowych w listach subskrypcyjnych

Wywołanie:

/rest/subscribers_list/addField

Dane:

Zwracane dane:

Kody błędów:

Wyświetlenie listy pól dodatkowych w podanej liście

Funkcja służy do wyświetlenia wszystkich pól dodatkowych w wybranej liście subskrypcyjnej

Wywołanie:

/rest/subscribers_list/getFields

Dane:

Zwracane dane:

Kody błędów:

Tworzenie kont

Metoda tworzy konto użytkownika. Można utworzyć zarówno konto główne jak i konto podrzędne.

Wywołanie:

POST /rest/account/create

Dane w POST:

Zwracane dane:

Kody błędów:

Subskrybenci – zarządzanie wieloma subskrybentami w pojedynczym żądaniu

Za pomocą poniższych metod można wykonywać dokładnie te same działania co przy zarządzaniu pojedynczymi subskrybentami, ale w żądaniu można przesłać do 100 subskrybentów naraz.

Dodawanie wielu subskrybentów

Metoda dodaje wielu subskrybentów jeśli nie było ich w liście subskrypcyjnej lub aktualizuje ich status i dane jeśli nie był w statusie „Aktywny” oraz „Do aktywacji”. W przypadku dodania tylko części z adresów (np. jeden z adresów jest niepoprawny) zostaje zwrócony kod 200 oraz dane dotyczące błędnego/błędnych adresów.

W przypadku nie dodania żadnego subskrybenta zostanie zwrócony błąd 422.

Wywołanie:

POST /rest/subscriber/addMultiple

Dane w POST:

Przykładowy request:

{"list":"id_hash",
"subscribers" : [{"email":"tester1@freshmail.pl",
"custom_fields":{"imie":"Hanna",
"kod_promocyjny":"abcde"} },
{"email":"tester2@freshmail.pl",
"custom_fields":{"imie":"Anna",
"kod_promocyjny":"efgh"} },
{"email":"tester3@freshmail.pl",
"custom_fields":{"imie":"Agata",
"kod_promocyjny":"wxyz"}}]} 

Kody błędów:

Przykład częściowych błędów, wysłany request:

{"list":"4zcnmd2ski",
"subscribers":[{"email":"poprawny@adres.email.pl"},
{"email":"niepoprawny adres email"}]}

Zwracane dane (kod odpowiedzi 200):

{"status":"OK",
"data":{
"inserted":1,
"not_inserted":1,
"errors":[{"email":"niepoprawny adres email",
"error":"Email address not correct",
"code":1301}]}}

Kody błędów zwracane dla poszczególnych subskrybentów są identyczne jak kody błędów dla metody /rest/subscriber/add

Modyfikowanie danych wielu subskrybentów

Metoda aktualizuje status i dane wielu subskrybentów

Wywołanie:

POST /rest/subscriber/editMultiple

Dane w POST:

Kody błędów:

Zwracane dane/informacje o błędach są identyczne jak w przypadku metody /rest/subscriber/addMultiple

Modyfikowanie pól dodatkowych wszystkich subskrybentów

Metoda aktualizuje wybrane pole dodatkowe i ustawia ustaloną wartość dla wszystkich subskrybentów

Wywołanie:

POST /rest/subscriber/updateFieldValue

Dane w POST:

Zwracane dane:

Kody błędów:

Przykład odpowiedzi niepoprawnej:

{"status":"ERROR",
"errors":[{
"message":"Niepoprawny adres url",
"code":1383
}]}

Przykład odpowiedzi poprawnej (kod odpowiedzi 200):

{"status":"OK", 
"data":{
"id":5
}}

{"status":"OK",
"data":{ "id":5,
"updated":150
}} 

{"status":"OK"} 

Pobieranie danych wielu subskrybentów

W przypadku gdy request jest częściowo niepoprawny (np. część adresów email nie istnieje) lub całkowicie niepoprawny (np. żaden z adresów email nie istnieje) zostaje zwrócony kod 200 oraz dane dotyczące błędnego/błędnych adresów.W przypadku gdy request jest całkowicie niepoprawny (np. żaden z adresów email nie istnieje) zostaje zwrócony kod 422 wraz z wiadomością błędu.

Wywołanie:

POST/rest/subscriber/getMultiple

Dane w GET:

Zwracane dane:

Kody błędów:

Kasowanie wielu subskrybentów

Metoda kasuje subskrybentów z listy subskrypcyjnej

Wywołanie:

POST /rest/subscriber/deleteMultiple

Dane w POST:

Kody błędów:

Zwracane dane/informacje o błędach są identyczne jak w przypadku metody /rest/subscriber/addMultiple

Dodawanie subskrybentów do listy odbiorców blokowanych

Metoda dodaje adresy subskrybentów do listy odbiorców blokowanych.

Wywołanie:

POST /rest/subscriber/addBlocks

Dane w POST:

Zwracane dane:

Kody błędów:

Kasowanie subskrybentów z listy odbiorców blokowanych

Metoda kasuje subskrybentów z listy odbiorców blokowanych. Akcja możliwa jedynie przy adresach zablokowanych własnoręcznie

Wywołanie:

POST /rest/subscriber/removeBlocks

Dane w POST:

Zwracane dane:

Kody błędów:

Subskrybenci – zarządzanie subskrybentami

Kontroler służy do dodawania i aktualizowania danych o subskrybentach w listach subskrypcyjnych.

Kody statusów subskrybentów

Dodanie subskrybenta

Metoda dodaje subskrybenta jeśli nie było go w liście subskrypcyjnej lub aktualizuje jego status i dane jeśli nie był w statusie „Aktywny” oraz „Do aktywacji”

Wywołanie:

POST /rest/subscriber/add

Dane w POST:

Kody błędów:

Modyfikowanie danych subskrybenta

Metoda aktualizuje status i dane subskrybenta

Wywołanie:

POST /rest/subscriber/edit

Dane w POST:

Kody błędów:

Pobieranie danych subskrybenta

Wywołanie:

GET /rest/subscriber/get/[list]/[email]

Dane w GET:

Zwracane dane:

Kody błędów:

Wyszukiwanie subskrybenta

Wywołanie:

GET /rest/subscriber/search/[email]

Dane w GET:

Zwracane dane:

Kody błędów:

Kasowanie subskrybenta

Metoda kasuje subskrybenta z listy subskrypcyjnej

Wywołanie:

POST /rest/subscriber/delete

Dane w POST:

Kody błędów:

Pobieranie historii akcji subskrybenta

Metoda pobiera ostatnie akcje subskrybenta

Wywołanie:

POST /rest/subscriber/getHistory

Dane w POST:

Przykładowy request:

{"email":"tester1@freshmail.pl"
"list":"4zcnmd2ski"
"limit":"30"}

Zwracane dane:

Kody błędów:

Przykład odpowiedzi niepoprawnej:

{"status":"ERROR",
"errors":[{
"message":"Subscriber doesn't exist",
"code":1313 }]}

Przykład odpowiedzi poprawnej:

{"status":"OK",
"data":[{
"name":"4 kampania wtorkowa z dnia 30.07.2013",
"email_topic":"Jesienna promocja",
"scheduled_sent":"2013-07-30 21:37:42",
"state":"DELIVERED",
"opens_count":"1",
"clicks_count":"2" }]}

Tworzenie nowej kampanii

Kontroler służy do tworzenia, sprawdzania i wysyłania kampanii.

Wywołanie:

POST /rest/campaigns/create

Dane w POST:

Zwracane dane:

Kody błędów:

Kampanie – obsługa kampanii

Wysłanie kampanii

Wywołanie:

POST /rest/campaigns/edit

Dane w POST:

Kody błędów:

Reszta kodów błędów jest identyczna jak w przypadku tworzenia kampanii.

Kasowanie kampanii

Wywołanie:
POST /rest/campaigns/delete

Dane w POST:

Kody błędów:

Wysłanie kampanii testowej

Wywołanie:
POST /rest/campaigns/sendTest

Dane w POST:

Przykładowy request:

{"hash":"hash_kampanii",
"emails":"test@test.pl",
"custom_fields":{
"imie":"Jan",
"nazwisko":"Kowalski"}}

lub

{"hash":"hash_kampanii",
"emails":["test1@test.pl","test2@test.pl"]}

Kody błędów:

Wysłanie kampanii

Wywołanie:
POST /rest/campaigns/send

Dane w POST:

Kody błędów:

Raporty – raporty z kampanii

Kontroler służy do pobierania raportów oraz list wysłanych kampanii.

Pobieranie listy wysłanych kampanii

Wywołanie:
GET /rest/reports/campaignsList/[page]

Dane w GET:

W odpowiedzi serwer zwróci listę 25 kampanii.

Zwracane dane:

Pobieranie zbiorczego raportu z kampanii

Wywołanie:

GET/rest/reports/campaign/[id_hash]

Dane w GET:

Zwracane dane:

Pobieranie zachowań subskrybentów w czasie

Wywołanie:

GET /rest/reports/campaignTimeDetails/[id_hash]

Dane w GET:

Zwracane dane:

tablica z kolejnymi działaniami subskrybentów w czasie:

{"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"}
]
}

Kody błędów:

Wiadomości SMS

Kontroler służy do wysyłki pojedynczych wiadomości SMS. Domyślnie wszystkie parametry muszą być przekazane w kodowaniu UTF-8.

Uwagi ogólne

Numery telefonu muszą być podawane w formacie 9 lub 11 cyfrowym (np. 48502602702 lub 502602702), możliwe jest także dodanie znaku „+” przed prefixem kraju (np. +48502602702). Obecnie sms'y są wysyłane tylko do polskich numerów, czyli do numerów z prefiksami rozpoczynających się od +48.

Treść pojedynczej wiadomości to standardowo do 160 znaków lub 70 znaków w przypadku wystąpienia chociaż jednego znaku specjalnego. Maksymalna długość wiadomości wynosi 459 znaków (lub 200 ze znakami specjalnymi) i jest wysłana jako 3 połączone SMS-y.

Znakami specjalnymi są wszystkie znaki nie mieszczące się w zestawie znaków:
@£$¥èéùìòÇØøÅå_^{}\[~]| ÆæßÉ!"#¤%&'()*€+,-./0-9:;<=>?A-ZÄÖÑܧ¿a-zäöñüà

Rodzaje wiadomości SMS

Kontroler umożliwia wysłanie wiadomości dwóch rodzajów: wiadomości typu PRO oraz 2WAY.

SMS typu PRO to wiadomość wysyłana z nadpisem alfanumerycznym, czyli zdefiniowanym polem nadawcy. Pole to nie może zawierać więcej niż 11 znaków z zestawu a-zA-Z0-9 oraz znak myślnika „-”. Aby korzystać z SMS typu PRO konieczne jest zgłoszenie nadpisu w systemie FreshMail.

SMS typu 2WAY to wiadomość wysłana z konkretnego numeru telefonu na który odbiorca może odpowiedzieć. Odpowiedź zostanie zarejestrowana w systemie FreshMail.

Cennik

Aby móc korzystać z wysyłki SMS należy w pierwszej kolejności podpisać umowę. Ceny za sms typu PRO, 2WAY są zawarte w umowie.

Wysyłanie wiadomości SMS  

Wywołanie: POST /rest/sms

Dane w POST.

Przykładowe żądanie (wykonane za pomocą biblioteki Curl):

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"}'

Poprawna odpowiedź:

{"status":"OK"}

Błędna odpowiedź:

{
   "status":"ERROR",
   "errors":[
      {
         "message":"SMS inscription (from) doesn't exist",
         "code":1105
      }
   ]
}

Kody błędów:

Pobranie raportu doręczenia wiadomości

sms/reports

Raporty wiadomości SMS

Przykładowe żądanie (wykonane za pomocą biblioteki Curl):

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"}'

Poprawna odpowiedź:

{
   "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
}

Pola zawarte w odpowiedzi:

Możliwe statusy wiadomości SMS

Jeśli wiadomość SMS nie została wysłana (czyli status wiadomości to ERROR) w dodatkowym parametrze error pojawi się powód nie wysłania wiadomości. Poniżej znajdują się możliwe kody błędów wysyłki wiadomości:

Pole modification_date:

W tym polu znajduje się czas ostatniej modyfikacji pola STATUS.

Odpowiedz na wiadomości typu 2WAY

Jeśli w polu from została umieszczona wartość 2way to wiadomość SMS jest wysyłana z numeru telefonu na który odbiorca może odpisać. Wszystkie odpowiedzi na wiadomości znajdują się w polu responses i mają format tablicy. Jeśli odbiorca SMSa odpowie na niego więcej niż jeden raz kolejne odpowiedzi będą elementami tablicy jak w przykładzie powyżej.

Wysyłanie pojedynczych maili

Kontroler służy do wysyłki pojedynczych wiadomości email.

API  V2 nie jest obecnie rozwijaną wersją API. Rekomendujemy używanie API V3, które jest bardziej wydajne i funkcjonalne.

Aby uruchomić usługę Email API i SMTP w pełnej wersji skontaktuj się z nami.

Ping – testowanie

Kontroler ten służy do przetestowania poprawności działania API. Osobno można przetestować poprawność działania żądań typu GET oraz żądań typu POST.

Wywołanie: GET /rest/ping
W odpowiedzi serwer zwróci „pong”.

Wywołanie: POST /rest/ping
W odpowiedzi serwer zwróci dane które wysyła się w POST.