Czym jest Event API?

W przeciwieństwie do Restful API, Event API wysyła dane na wskazany adres, twórca skryptu musi jedynie odebrać dane i zwrócić odpowiedni komunikat.

 

Jak włączyć EventAPI?

Aby uruchomić usługę po pierwsze przygotuj skrypt który będzie odpowiedzialny za odbieranie danych

Używając tego przykładu pamiętaj aby podmienić nazwę panelu oraz klucz secret key
Zwróć uwagę na porównywanie sum kontrolnych

Zanim przejdziesz do pisania skryptu odbierającego dane z EmailLabs, przygotuj nazwę panelu oraz klucz secret key, chociaż dane te nie są wymagane przydadzą się w procesie autoryzacji przesłanych danych.

1) Nagłówki wysyłane przez EmailLabs oprócz standardowych nagłówków HTTP posiadają 4 dodatkowe które pozwolą nam stwierdzić czy dane faktycznie pochodzą z EmailLabs:

X-EMAILLABS-EV – Określa typ wydarzenia ( NEW_EVENTS – wysyłane po raz pierwszy lub REPEAT_EVENTS – wysłano ponownie z powodu błędu w odbiorze )

X-EMAILLABS-TS – Czas wysłania danych przez serwery EmailLabs w formacie Unix Time Stamp

X-EMAILLABS-MT – Czas wysłania danych przez serwery EmailLabs w formacie Unix Time Stamp wraz z mikrosekundami

X-EMAILLABS-ID – Unikalna klucz identyfikujący wysłane dane zakodowane za pomocą MD5 w formacie X-EMAILLABS-TS, X-EMAILLABS-MT, nazwa panelu, klucz secret key. Dane kodowane są w podanej kolejności oraz oddzielone znakiem |

Nagłówek X-EMAILLABS-ID może być wykorzystywany do identyfikacji serwerów EmailLabs ( jeżeli klucz wysłany przez serwer zgadza się z tym który wygenerujesz sam zgodnie ze wzorem oznacza to że dane są poprawne )

niestandardowy jest również nagłówek USER_AGENT w przypadku Webhooks EmailLabs wyblada następująco:

2) Dane wysyłane są metodą POST w polu „p” zakodowanym w Base64. Po odkodowaniu tych danych otrzymasz poszczególne wydarzenia zakodowane w JSON ( jak rozumieć zawarte dane przeczytasz niżej )

Prosimy o nie przetwarzanie danych wewnątrz skryptu odbierającego dane. EmailLabs zaleca wyłącznie zapis odebranych danych do pliku i przetwarzanie ich w osobnym skrypcie.

3) Gdy odbierzez i odkodujesz dane zwróć serwerowi napis ok używając małych liter oraz eliminujac białe znaki.

Tylko taka odpowiedź będzie uznawana za poprawną i nie bedą wysyłane ponownie

gdy skrypt do odbioru danych jest już na miejscu, zaloguj się do panelu klienta a następnie przejdź do ustawień API oraz wypełnij wymagane dane:

Zrzut ekranu 2015-08-04 o 14.27.24

wpisane dane możesz przetestować przed zapisem klikając przycisk „Wykonaj test” pod przyciskiem pojawi się odpowiedni komunikat informujący o tym jak przebiegł test.

Zrzut ekranu 2015-08-04 o 14.27.27

Jeżeli korzystałeś z naszego przykładu, w folderze w którym umieszczony jest skrypt powinien pojawić się plik z wynikiem przesłanym przez serwer. „res_YYYY-MM-DD_HH:MM:SS.json”

Jak rozumieć odebrane dane?

Poniższa legenda jakie dane możemy uzyskać z serwerów EmailLabs

Pole Opis

event_type
Typ wydarzenia:
open_tracking, click_tracking, unsubscribe, hardbounce, spambounce, dropped ( Aby wyliczyć ilość statusów „ok” należy od liczby wysłanych wiadomości e-mail odjąć statusy: hardbounce, spambounce oraz  dropped  )

to
Odbiorca wiadomości

from
Nadawca wiadomości

subject
Temat wiadomości

tags
Tablica z tagami

message_id
Unikalny identyfikator wiadomości ( nadana przez nadawce )

message_uid
Unikalny identyfikator wiadomości ( nadawany przez EmailLabs )

injected_time
Data przyjęcia wiadomości

panel
Nazwa panelu

smtp_account
Konto SMTP z którego wysłana została wiadomość

data_ext
Dane dodatkow charakterystyczne dla danego typu wpisu ( zazwyczaj zawiera IP, USER_AGENT, nazwę przeglądarki oraz platformy )

created_at
Data utworzenia wpisu

updated_at
Data ostatniej modycikacji wpisu