Czym jest API?

Zbiór poleceń pomagających zintegrować platformę EmailLabs z Państwa oprogramowaniem np. CRM.

 

Jak to działa?

Platforma API obsługiwana jest w standardzie REST poprzez protokół HTTP oraz HTTPS, z wykorzystaniem metody autoryzacji Basic Auth. Rozwiązania tego typu pozwalają szybko połączyć się z EmailLabs, oraz pobrać niezbędne dane, bez konieczności logowania się do panelu administracyjnego.

 

Od czego zacząć?

Aby połączyć się z API EmailLabs, w pierwszej kolejności skopiuj z panelu klucze „App Key” oraz „Secret Key”. Uzyskasz go logując się do panelu pod adresem: panel.emaillabs.net.pl w zakładce Administrator > API.

Pamiętaj aby nigdy nie ujawniać kluczy zapisanych w panelu

 

Jak budować zapytania?

Zapytania budowane są w oparciu o adres serwisu webowego obsługującego zapytania dodając na końcu nazwę akcji:

https://api.emaillabs.net.pl/api/{nazwaAkcji}

 

Jak nawiązać połączenie?

Na wcześniej wybrany adres należy wysłać zapytanie jedną z obsługiwanych metod ( POST, GET, PUT, DELETE ), dodatkowo w celu przeprowadzenia autoryzacji, w nagłówku zapytania należy umieścić następujący parametr:

Wartość AppKey:SecretKey musi być zakodowana w BASE64
Wybranie metody ( POST, GET, PUT, DELETE ) jest uzależnione od danej akcji.
Metody autoryzacji Basic Auth należy używać w każdym zapytaniu

 

Odpowiedź z serwera

Po wysłaniu zapytania do serwera, ten zwróci nam odpowiedź zawierającą wynik zapytania lub komunikat błędu jaki powstał podczas jego wykonywania. Wynik zwracany jest w formacie JSON. W odpowiedzi serwera zawsze znajdują się następujące pola:

code – status zwrócony przez serwer w formie numerycznej.

status – status zwrócony przez serwer w formie tekstowej.

Status Opis
200 Akcja została zrealizowana poprawnie
404 Akcji nie odnaleziono lub w wyniku danego zapytania nie odnaleziono żadnego obiektu
500 Wystąpił błąd uniemożliwiający poprawne odpytanie API

message – wiadomość z serwera w formie teksotwej.

data – tablica z rezultatem zwróconym przez serwer.

Przykładowa odpowiedź serwera:

 

Jak budować parametr filter?

Parametr filter jest opcjonalny i dozwolony tylko w niektórych metodach. Pozwala zawęzić zapytanie do konkretnego wpisu lub grupy konkretnych wpisów. Aby używać wymienionej opcji w protokole GET należy dodać następujący zapis: „nazwa_pola::wartość_wyszukiwania”. Istnieje możliwość przeszukiwania rezultatu po wielu polach. Do oddzielenia kolejnych parametrów należy używać znaku | np. „nazwa_pola1::wartość_1|nazwa_pola2:wartość_2”

istnieje również możliwość używania słów kluczowych takich jak from oraz to np. „nazwa_pola.from::wartość”

 

Zbiór funkcji dostępnych w serwisie:

Adres Metoda Parametry Opis Dokumentacja
/api/smtp_events/{status} GET from_time – data w formie time stamp od którego dnia wpisy mają zostać pobrane

offset – numer strony

limit – ilość rezultatów na stronie

sort – po jakim polu odbywa się sortowanie

filter – dodatkowe filtrowanie

Umożliwia pobranie wiadomości e-mail w oparciu o status jaki ostatecznie otrzymała Link
/api/emails GET offset – numer strony

limit – ilość rezultatów na stronie

sort – po jakim polu odbywa się sortowanie

filter – dodatkowe filtrowanie

Umożliwia pobranie wiadomości e-mail wysłanych z pośrednictwem kont SMTP Link
/api/smtp GET n/d Pozwala pobrać listę kont SMTP przypisanych do danego panelu. Link
/api/opens GET offset – numer strony

limit – ilość rezultatów na stronie

sort – po jakim polu odbywa się sortowanie

filter – dodatkowe filtrowanie

Umożliwia pobranie otwarć wiadomości przez użytkowników. Link
/api/clicks GET offset – numer strony

limit – ilość rezultatów na stronie

sort – po jakim polu odbywa się sortowanie

filter – dodatkowe filtrowanie

Umożliwia pobranie ilości kliknięć w linki użytych we wiadomościach e-mail. Link
/api/blacklist_reasons GET n/d Pozwala pobrać listę powodów odrzuceń na czarnej liście. Link
/api/blacklists/email/{adres e-mail} GET adres e-mail – przekazywany w adresie URL jako parametr Pozwala sprawdzić czy na czarniej liście znajduję się zadany adres e-mail. Link
/api/blacklists GET offset – numer strony

limit – ilość rezultatów na stronie

sort – po jakim polu odbywa się sortowanie

filter – dodatkowe filtrowanie

Pozwala pobrać czarną listę adresów e-mail, do których nie będzie dostarczana poczta. Link
/api/blacklists POST account – nazwa konta SMTP

email – adres e-mail do dodania

reason – powód dodania do czarnej listy

Pozwala dodać adres e-mail do czarnej listy Link
/api/new_sendmail POST Więcej w dokumentacji… Pozwala wysyłać wiadomości e-mail za pośrednictwem API Link
/api/sendmail_templates POST Więcej w dokumentacji… Pozwala wysyłać wiadomości e-mail za pośrednictwem API z wykorzystaniem szablonów Link
/api/add_template POST Więcej w dokumentacji… Pozwala dodać nowy szablon wiadomości Link
/api/agregate GET smtp_account – nazwa konta SMTP

date_from – data od w formie time stamp

date_to – data do w formie time stamp

Pozwala pobrać dane zagregowane np. na potrzeby stworzenia wykresu Link
/api/agregate_tags GET smtp_account – nazwa konta SMTP

date_from – data od w formie time stamp

date_to – data do w formie time stamp

Pozwala pobrać dane zagregowane np. na potrzeby stworzenia wykresu z podziałem na tagi Link
/api/blacklists/email/{adres e-mail} DELETE adres e-mail – przekazywany w adresie URL jako parametr Pozwala usunąć adres e-mail z czarnej listy Link
/api/is_mail_tmp/email/{adres e-mail} GET adres e-mail – przekazywany w adresie URL jako parametr Pozwala sprawdzić czy adres e-mail należy do serwisów tymczasowych Link