asendo.pl tel: 22 211 20 22 Dokumentacja techniczna asendo APIEmail Spis treści 1. Wprowadzenie...2 2. Komunikaty...3 3. Zarządzanie kontaktami...7 4. Szablony email...19 5. Nadawcy email...22 6. Kampanie asendo Data...25 7. Pobranie salda...35 8. Historia zmian...37 1
1. Wprowadzenie Interfejs Zdalnej Obsługi asendo APIEmail przy pomocy protokołu HTTPS umożliwia zdalną komunikację z systemem wysyłek. Dzięki temu możliwe jest wysyłanie, sprawdzanie statusu wysłanych wiadomości email, jak również dostęp do innych funkcji bez konieczności logowania się do Panelu Klienta. Komunikacja z platformą asendo.pl odbywa się poprzez wywołanie specjalnego adresu URL metodą POST lub metodą GET z odpowiednimi parametrami. Jako odpowiedź zwracany jest dokument w formacie XML zawierający pobrane dane lub jedynie informujący o wyniku wykonanej operacji. Dedykowanym sposobem przesyłu danych jest opcja POST. W przypadku GET należy pamiętać o odpowiednim kodowaniu parametrów oraz o maksymalnej długości przesyłanych informacji. W celu autoryzacji do systemu wysyłek należy w swoim Panelu Klienta w dziale Moje konto Konto WebAPI stworzyć użytkownika do autoryzacji podając unikalną nazwę i hasło. Maksymalna wielkość pojedynczego zgłoszenia do wysyłki to 100.000 adresów. Zalecane jest przesyłanie mniejszych porcji danych np. 100-5000 odbiorców w jednym zgłoszeniu. Usługa komunikacji zdalnej obsługi dostępna jest pod adresem: /api/email Można również skorzystać z gotowego klienta PHP dostępnego pod adresem: /files/apiemail_php.zip 2
2. Komunikaty Status ogólny W przypadku wykonania akcji zapisu lub usunięcia wybranego elementu systemu komunikat zwrotny zawiera ogólny status reprezentujący wykonaną akcję. W przypadku poprawnego wykonania zadania element XML zawiera komunikat OK, w przeciwnym razie generowany jest błąd z kodem identyfikującym przyczynę niepowodzenia. Komunikat błędu W momencie braku określenia akcji, zablokowanego konta lub podania błędnych danych uwierzytelniających, asendo.pl wygeneruje dokument w formacie XML z informacją na temat błędu który wystąpił. Przykładowo w sytuacji podania niewłaściwego loginu lub hasła klient zobaczy następujący komunikat: <asendo username="uzytkownik"> <error id="101">err: Nieprawidlowy login lub haslo</error> Jeśli nie zostanie określona żadna akcja do wykonania, system zwróci komunikat: <asendo username="uzytkownik"> <error id="103">err: Nie okreslono akcji do wykonania</error> Objaśnienie poszczególnych sekcji XML <error></error> Zawiera informację o przyczynie niepowodzenia: id identyfikator błędu 3
Lista kodów błędów zwracanych przez API Zwracane błędy przedstawione są w postaci liczbowej i opisowej. Poniżej znajduje się tabela z kodami oraz przyporządkowanymi do nich opisami tekstowymi. Nieujęte poniżej odpowiedzi systemu zwracane są z domyślnymi wartościami opisanymi w odpowiedniej sekcji dokumentacji. Kod Ogólne 100 ERR: Nie podano danych uwierzytelniajacych 101 ERR: Nieprawidlowy login lub haslo 102 ERR: Uzytkownik nie ma uprawnien do korzystania z APIEmail 103 ERR: Nie okreslono akcji do wykonania 104 ERR: Niedozwolona wartosc parametru action 105 ERR: Wystąpil problem. Prosimy sprobowac pozniej lub skontaktowac sie z administratorem 106 ERR: Odczekaj sekunde przed kolejnym zapisem 107 ERR: Nie podano wymaganych parametrow 108 ERR: Usluga jest tymczasowa niedostepna 109 ERR: Adres IP zostal zablokowany Grupy i kontakty 200 ERR: Nie podano identyfikatora grupy group_id 201 ERR: Brak grupy o podanym identyfikatorze 202 ERR: Nie podano nazwy grupy 203 ERR: Nazwa grupy jest nieprawidlowa 204 ERR: Grupa o podanej nazwie juz istnieje 205 ERR: Nie podano numeru telefonu, telefonu stacjonarnego lub adresu email 206 ERR: Podaj prawidlowy 9 cyfrowy numer telefonu mobilnego 207 ERR: Podaj prawidlowy 9 cyfrowy numer stacjonarny 4
208 ERR: Podaj prawidlowy adres email 209 ERR: Nie podano identyfikatora kontaktu do usuniecia 210 ERR: Podano nieprawidlowy identyfikator kontaktu Wysyłka wiadomości 301 ERR: Nie podano tematu wiadomosci 302 ERR: Brak identyfikatora nazwy nadawcy 303 ERR: Identyfikator nadawcy jest nieprawidlowy 304 ERR: Nadawca nie jest aktywny lub zweryfikowany 305 ERR: Podano nieprawidlowy identyfikator grup 306 ERR: Nie znaleziono adresu/adresow email 307 ERR: Podano nieprawidlowe adresy email 308 ERR: Maksymalnie mozna wyslac do 100.000 odbiorcow 309 ERR: Nie podano tresci wiadomosci 310 ERR: System antyspamowy uznal wiadomosc za potencjalny SPAM 311 ERR: Podana data wysylki jest nieprawidlowa 312 ERR: Twoje saldo jest niewystarczajace Kampanie 401 ERR: Brak identyfikatora kampanii order_id 402 ERR: Nieprawidlowy identyfikator kampanii order_id Szablony 501 ERR: Brak nazwy szablonu lub nazwa jest nieprawidlowa 502 ERR: Brak zawartosci tresci szablonu 503 ERR: Nieprawidlowy identyfikator szablonu template_id Nadawcy 601 ERR: Brak nazwy nadawcy 602 ERR: Brak adresu email nadawcy lub adres jest niepoprawny 5
603 ERR: Podany nadawca już istnieje 604 ERR: Podana nazwa jest nieprawidlowa 6
3. Zarządzanie kontaktami Pobranie listy grup Wywołanie adresu Aby przy pomocy Zdalnej obsługi pobrać listę dostępnych grup kontaktowych należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/email/? username=uzytkownik&password=haslo&action=get_groups Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String get_groups Aby pobrać listę dostępnych grup należy umieścić tutaj get_groups Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego pobrania listy grup kontaktowych klient otrzyma przykładowo dane o następującej strukturze: <asendo username="uzytkownik" action="get_groups"> <list> <group group_id="2" count="1" created="2014-03-27 14:07:21">Grupa 2</group> <group group_id="1" count="2" created="2014-03-27 14:07:21">Grupa 1</group> </list> 7
Objaśnienie poszczególnych sekcji XML <list></list> Zawiera listę dostępnych grup <group></group> Zawiera szczegółowe dane grupy: group_id identyfikator count ilość kontaktów wchodzących w skład grupy created data stworzenia w formacie RRRR-MM-DD GG:MM:SS Wartość sekcji stanowi nazwy grupy Oprócz tego może zostać wygenerowany błąd ogólny. Może to nastąpić np. w sytuacji gdy konto użytkownika nie jest aktywne lub wystąpił inny problem opisany w komunikatach błędów. Przykładowo: <asendo username="uzytkownik" action="nieznana-akcja"> <error id="104">err: Niedozwolona wartosc parametru action</error> Zapis nowej grupy Wywołanie adresu Aby przy pomocy Zdalnej obsługi wykonać zapis nowej grupy kontaktowej należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/email/? username=uzytkownik&password=haslo&action=add_group&name=kontakty 8
Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String add_group name String Kontakty Aby zapisać nową grupę należy umieścić tutaj add_group Nazwa grupy w postaci znaków alfanumerycznych. Maksymalnie 100 znaków Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego zapisu grupy klient otrzyma przykładowo zwrotną informację o następującej strukturze: <asendo username="uzytkownik" action="add_group"> <group group_id="3" name="kontakty" created="2014-04-01 16:11:44">OK</group> Objaśnienie poszczególnych sekcji XML <group></group> Zawiera dane zapisanego elementu w systemie: group_id identyfikator grupy name nazwa created data stworzenia w formacie RRRR-MM-DD GG:MM:SS Wartość sekcji stanowi status wykonanej operacji 9
Oprócz tego może zostać wygenerowany błąd. Może to nastąpić np. w sytuacji gdy nie podano nazwy grupy lub jest ona nieprawidłowa z powodu błędnych znaków. <asendo username="uzytkownik" action="add_group"> <error id="202">err: Nie podano nazwy grupy</error> Usunięcie wybranej grupy Wywołanie adresu Aby przy pomocy Zdalnej obsługi usunąć wybraną grupę wraz z kontaktami wchodzącymi w jej skład należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/email/? username=uzytkownik&password=haslo&action=remove_group&group_id=1 Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String remove_group group_id Interger 1 Aby usunąć wybraną grupę wraz z kontaktami należy umieścić tutaj remove_group Identyfikator swojej grupy, którą chcemy usunąć 10
Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego usunięcia grupy klient otrzyma przykładowo informację o następującej strukturze: <asendo username="uzytkownik" action="remove_group"> <group group_id="1">ok</group> Objaśnienie poszczególnych sekcji XML <group></group> Zawiera dane usuniętego elementu: group_id identyfikator grupy Wartość sekcji stanowi status wykonanej operacji Pobranie listy kontaktów Wywołanie adresu Aby przy pomocy Zdalnej obsługi pobrać listę kontaktów należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/email/? username=uzytkownik&password=haslo&action=get_contacts&group_id=1 11
Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String get_contacts group_id Interger 1 Aby pobrać kontakty z wybranej grupy należy umieścić tutaj get_contacts Identyfikator swojej grupy, z której chcemy pobrać kontakty Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego pobrania listy klient otrzyma przykładowo dokument: <asendo username="uzytkownik" action="get_contacts"> <list group_id="1"> <contact contact_id="2" first_sub_name="" name="" phone="" stationary="" email="test@asendo.pl" created="2014-03-27 14:35:14"/> </list> Objaśnienie poszczególnych sekcji XML <list></list> Zawiera listę kontaktów. Dostępne atrybuty: group_id identyfikator grupy kontaktowej <contact></contact> Zawiera szczegółowe dane kontaktu: 12
contact_id identyfikator first_sub_name imię i nazwisko name nazwa kontaktu phone telefon mobilny stationary telefon stacjonarny email adres email created data stworzenia w formacie RRRR-MM-DD GG:MM:SS Zapis kontaktu Wywołanie adresu Aby przy pomocy Zdalnej obsługi wykonać zapis kontaktu należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/email/? username=uzytkownik&password=haslo&action=add_contact&group_id=1&email=test @asendo.pl Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String add_contact group_id Interger 1 Aby dodać nowy kontakt należy umieścić tutaj add_contact Identyfikator grupy do której chcemy przypisać kontakt email String test@asendo.pl Adres email kontaktu 13
Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego zapisu klient otrzyma przykładowo informację o następującej strukturze: <asendo username="uzytkownik" action="add_contact"> <contact contact_id="2" first_sub_name="" name="" phone="" stationary="" email="test@asendo.pl" created="2014-04-02 11:02:47">OK</contact> Objaśnienie poszczególnych sekcji XML <contact></contact> Zawiera szczegółowe dane zapisanego elementu: contact_id identyfikator kontaktu first_sub_name imię i nazwisko name nazwa phone telefon mobilny stationary telefon stacjonarny email adres email created data stworzenia w formacie RRRR-MM-DD GG:MM:SS Wartość sekcji stanowi status wykonanej operacji. Usunięcie kontaktu Wywołanie adresu Aby przy pomocy Zdalnej obsługi usunąć wybrany kontakt należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: 14
/api/email/? username=uzytkownik&password=haslo&action=remove_contact&contact_id=2 Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String remove_contact contact_id Interger 2 Aby usunąć kontakt należy umieścić tutaj remove_contact Identyfikator usuwanego kontaktu Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego usunięcia klient otrzyma przykładowo poniższą informację: <asendo username="uzytkownik" action="remove_contact"> <contact contact_id="2">ok</contact> Objaśnienie poszczególnych sekcji XML <contact></contact> Zawiera dane dotyczące usuniętego elementu: contact_id identyfikator kontaktu Wartość sekcji stanowi status wykonanej operacji. 15
Lista duplikatów Wywołanie adresu Aby przy pomocy Zdalnej obsługi pobrać listę duplikowanych adresów email należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/email/? username=uzytkownik&password=haslo&action=get_duplicates Lista duplikatów pobierana jest w obrębie danej grupy. Mając więc dwa identyczne adresy email w różnych grupach system nie potraktuje kolejnego adresu jako powielenia. Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String get_duplicates Aby pobrać listę duplikatów należy umieścić tutaj get_duplicates Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego pobrania listy klient otrzyma przykładowo zwrotkę o następującej strukturze: <asendo username="uzytkownik" action="get_duplicates"> <list> <contact email="test@asendo.pl" group_id="1" count="1"/> </list> 16
Lub gdy nie znaleziono duplikatów: <asendo username="uzytkownik" action="get_duplicates"> <list/> Objaśnienie poszczególnych sekcji XML <list></list> Zawiera listę ewentualnych duplikatów <contact></contact> Zawiera dane dotyczące powielenia: email adres email group_id identyfikator grupy count ilość powielonych rekordów o takim samym adresie email w obrębie tej samej grupy Usunięcie duplikowanych adresów email Wywołanie adresu Aby przy pomocy Zdalnej obsługi usunąć powielone adresy email należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/email/? username=uzytkownik&password=haslo&action=remove_duplicates Usuwanie jest realizowane w obrębie danej grupy. Mając więc dwa identyczne adresy w różnych grupach system nie potraktuje drugiego adresu jako powielenia. 17
Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String remove_duplicates Aby usunąć duplikaty należy umieścić tutaj remove_duplicates Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego usunięcia rekordów klient otrzyma przykładowo następującą informację zwrotną: <asendo username="uzytkownik" action="remove_duplicates"> <list> <contact contact_id="2" email="test@asendo.pl"/> </list> Objaśnienie poszczególnych sekcji XML <list></list> Zawiera listę usuniętych duplikatów <contact></contact> Zawiera szczegółowe dane usuniętego rekordu: contact_id identyfikator kontaktu email adres email 18
4. Szablony email Pobranie listy dostępnych szablonów Wywołanie adresu Aby przy pomocy Zdalnej obsługi pobrać dostępne szablony email należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/email/? username=uzytkownik&password=haslo&action=get_templates Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String get_templates Aby pobrać dostępne szablony należy umieścić tutaj get_templates Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego pobrania klient otrzyma przykładowo następującą informację zwrotną: <asendo username="uzytkownik" action="get_templates"> <list> <template template_id="1" name="szablon" created="2014-04-01 10:14:11"> <html><![cdata[<p>treść szablonu</p>]]></html> </template> </list> 19
Objaśnienie poszczególnych sekcji XML <list></list> Zawiera listę szablonów <template></template> Zawiera szczegółowe dane dotyczące szablonu: template_id identyfikator name nazwa szablonu created data stworzenia w formacie RRRR-MM-DD GG:MM:SS <html></html> Zawartość szablonu email Zapis nowego szablonu wiadomości email Wywołanie adresu Aby przy pomocy Zdalnej obsługi wykonać zapis szablonu email należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/email/? username=uzytkownik&password=haslo&action=add_template&name=szablon&html= Wiadomość%20email Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String add_template Aby zapisać szablon należy umieścić tutaj add_template 20
name String Szablon Nazwa szablonu w postaci znaków alfanumerycznych. Maksymalnie 100 znaków html String Wiadomość email Treść szablonu email Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego zapisu nowego szablonu klient otrzyma przykładowo następującą odpowiedź: <asendo username="uzytkownik" action="add_template"> <template template_id="2" name="szablon" created="2014-04-02 12:24:56">OK</template> Objaśnienie poszczególnych sekcji XML <template></template> Zawiera dane dotyczące zapisanego szablonu: template_id identyfikator szablonu name - nazwa created data zapisu w formacie RRRR-MM-DD GG:MM:SS 21
5. Nadawcy email Pobranie listy Wywołanie adresu Aby przy pomocy Zdalnej obsługi pobrać listę nadawców email należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/email/? username=uzytkownik&password=haslo&action=get_senders Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String get_senders Aby pobrać listę nadawców należy umieścić tutaj get_senders Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego pobrania listy klient otrzyma przykładowo następującą informację zwrotną: <asendo username="uzytkownik" action="get_senders"> <list> <sender sender_id="1" name="tester" email="test@asendo.pl" active="1" created="2014-03-19 12:14:47"/> </list> 22
Objaśnienie poszczególnych sekcji XML <list></list> Zawiera listę nadawców <sender></sender> Zawiera dane dotyczące nadawcy: sender_id identyfikator name - nazwa email - adres email active flaga określająca możliwość ustawienia do wysyłki: 0 nie 1 tak created data utworzenia w formacie RRRR-MM-DD GG:MM:SS Zapis nowego nadawcy Wywołanie adresu Aby przy pomocy Zdalnej obsługi stworzyć nowego nadawcę email należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/email/? username=uzytkownik&password=haslo&action=add_sender&name=test&email=test @asendo.pl Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI 23
action String add_sender name String Test Aby zapisać nadawcę należy umieścić tutaj add_sender Nazwa nadawcy w postaci ciągu alfanumerycznego, minimum 5 znaków, maksymalnie 60 znaków email String test@asendo.pl Adres email nadawcy Nowo dodany nadawca email wymaga aktywacji, poprzez kliknięcie w link wysłany przez system na podany w żądaniu adres. Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego zapisu klient otrzyma przykładowo następującą informację zwrotną: <asendo username="uzytkownik" action="add_sender"> <sender sender_id="2" name="test" email="test@asendo.pl" created="2014-04-02 12:47:13">OK</sender> Objaśnienie poszczególnych sekcji XML <sender></sender> Zawiera dane dotyczące zapisanego elementu: sender_id identyfikator nadawcy email name nazwa email adres email created data zapisu w postaci RRRR-MM-DD GG:MM:SS 24
6. Kampanie asendo Data Pobranie listy zamówień Wywołanie adresu Aby przy pomocy Zdalnej obsługi pobrać listę zamówionych kampanii email należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/email/? username=uzytkownik&password=haslo&action=get_campaigns Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String get_campaigns Aby pobrać dostępne zamówienia należy umieścić tutaj get_campaigns Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML ze spisem zamówionych kampanii. W przypadku prawidłowego pobrania klient otrzyma przykładową odpowiedź: <asendo username="uzytkownik" action="get_campaigns"> <list> <order order_id="tta1" count="2" price="0.02" sender="test test@asendo.pl" planned="0" send_date="2014-04-02 09:29:00" status="w trakcie realizacji" created="2014-04-02 09:28:34"> <html><![cdata[<p>treść wiadomości</p>]]></html> 25
</order> </list> Objaśnienie poszczególnych sekcji XML <list></list> Lista zamówionych kampanii <order></order> Szczegółowe informacji dotyczące kampanii: order_id identyfikator zamówienia count ilość odbiorców price koszt kampanii PLN netto sender nadawca wiadomości planned flaga określająca czy wysyłka jest zaplanowana: 0 nie 1 tak send_date data wysyłki w formacie RRRR-MM-DD GG:MM status status kampanii created data zamówienia w formacie RRRR-MM-DD GG:MM:SS <html></html> Zawiera treść przesyłanej wiadomości Pobranie raportu kampanii Wywołanie adresu Raport kampanii pozwala śledzić status wiadomości. Aby przy pomocy Zdalnej obsługi pobrać raport należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/email/? username=uzytkownik&password=haslo&action=get_raport&order_id=tta1 26
Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String get_raport Aby pobrać raport należy umieścić tutaj get_raport order_id String TTA1 Identyfikator kampanii Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego pobrania raportu klient otrzyma przykładowo następującą informację zwrotną: <asendo username="uzytkownik" action="get_raport"> <order order_id="tta1" count="2" price="0.02" status="w trakcie realizacji" created="2014-04-02 09:28:34"> <email email_id="1" email="odbiorca1@domena.pl" status="w trakcie wysylki" raport_date="2014-04-02 10:15:12" readed_date="" reason="" city="" ip="" lng="" lat=""/> <email email_id="2" email="odbiorca2@domena.pl" status="w trakcie wysylki" raport_date="2014-04-02 10:15:10" readed_date="" reason="" city="" ip="" lng="" lat=""/> </order> Objaśnienie poszczególnych sekcji XML <order></order> Szczegóły kampanii: order_id identyfikator zamówienia count ilość odbiorców price koszt kampanii PLN netto status status kampanii 27
created data zamówienia w formacie RRRR-MM-DD GG:MM:SS <email></email> Szczegóły wiadomości email: email_id identyfikator wiadomości email adres odbiorcy status status wiadomości raport_date data raportu w formacie RRRR-MM-DD GG:MM:SS readed_date data odczytania wiadomości w formacie RRRR-MM-DD GG:MM:SS reason ewentualny powód niedostarczenia/niewysłania wiadomości city dane geolokalizacji dotyczące miejsca odebrania wiadomości ip adres IP osoby odczytującej wiadomość lub adres proxy serwera poczty lat, lng współrzędne dotyczące miejsca odebrania wiadomości Pobranie odpowiedzi email Wywołanie adresu Mechanizm ten pozwala na odczytanie odpowiedzi przesłanych przez użytkowników. Aby przy pomocy Zdalnej obsługi pobrać zapisane odpowiedzi należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce może wyglądać następująco: /api/email/? username=uzytkownik&password=haslo&action=get_answers&order_id=tta1 Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI 28
action String get_answers Aby pobrać odpowiedzi należy umieścić tutaj get_answers order_id String TTA1 Identyfikator kampanii Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego pobrania listy odpowiedzi klient otrzyma informację zwrotną o poniższej strukturze: <asendo username="uzytkownik" action="get_answers"> <order order_id="tta1"> <answer email="test@asendo.pl" subject="temat wiadomości" from="test" created="2013-12-31 11:53:34"> <html>><![cdata[treść odpowiedzi]]></html> </answer> </order> Objaśnienie poszczególnych sekcji XML <order></order> Dane dotyczące kampanii: order_id identyfikator zamówienia <answer></answer> Szczegółowe dane odczytanej odpowiedzi: email adres nadawcy from nazwa nadawcy subject temat wiadomości created data odebrania raportu w formacie RRRR- MM-DD GG:MM:SS html element zawierający treść odpowiedzi 29
Pobranie statystyk kampanii Wywołanie adresu Mechanizm statystyk pozwala śledzić ilość wysłanych, odczytanych lub niedoręczonych wiadomości wybranej kampanii. Aby przy pomocy Zdalnej obsługi pobrać statystyki należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/email/? username=uzytkownik&password=haslo&action=get_stats&order_id=tta1 Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String get_stats Aby pobrać statystyki należy umieścić tutaj get_stats order_id String TTA1 Identyfikator kampanii Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego pobrania danych klient otrzyma przykładowo następującą informację zwrotną: <asendo username="uzytkownik" action="get_stats"> <stat order_id="tta1" status="w trakcie realizacji" created="2014-04-02 09:28:34"> <readed>0</readed> <noserved>0</noserved> <send>2</send> <nosend>0</nosend> 30
<wait>1</wait> </stat> Objaśnienie poszczególnych sekcji XML <stat></stat> Dane dotyczące kampanii: order_id identyfikator zamówienia status status kampanii created data zamówienia w formacie RRRR-MM-DD GG:MM:SS <readed></readed> <noserved></noserved> <send></send> <nosend></nosend> <wait></wait> Ilość odczytanych wiadomości Ilość wiadomości niedostarczonych. Możliwy powód: - brak takiego adresu - odrzucenie przez serwer Ilość wiadomości wysłanych Ilość wiadomości niewysłanych. Możliwy powód: - adres znajduje się na czarnej liście - nieprawidłowy format email Ilość wiadomości w trakcie wysyłki (oczekujące na raport) Wysyłka wiadomości Wywołanie adresu Aby przy pomocy Zdalnej obsługi zrealizować wysyłkę wiadomości należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/email/? username=uzytkownik&password=haslo&action=send&subject=temat&sender_id=1&r ecipients=odbiorca@domena.pl&message=wiadomość 31
Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String haslo Hasło do konta WebAPI action String send subject String Temat sender_id Integer 1 recipients String group_id String 1,2 odbiorca@asendo.pl, odbiorca2@asendo.pl Aby wysłać wiadomość należy umieścić tutaj send Temat wiadomości. Maksymalnie można wprowadzić 80 znaków Identyfikator aktywnego nadawcy email Lista odbiorców oddzielona przecinkiem Lista grup odbiorców oddzielona przecinkiem message String Wiadomość Treść wiadomości email template_id Integer 1 Identyfikator szablonu send_date DateTime 2014-03-28 13:45 test Integer 1 Parametr opcjonalny pozwalający na określenie terminu wysyłki w formacie RRRR-MM-DD GG:MM Parametr opcjonalny, zdefiniowanie wartości 1 powoduje, że na adres email podany podczas rejestracji konta zostanie wysłana wiadomość testowa Definiowanie odbiorców Odbiorcę wiadomości możemy zdefiniować na 2 różne sposoby, poprzez: przekazanie listy adresatów oddzielonych przecinkiem w parametrze recipients określenie identyfikatorów grupy/grup w parametrze group_id Wyższy priorytet ma opcja druga. 32
Definiowanie treści wiadomości Treść wiadomości możemy zdefiniować na 2 różne sposoby, poprzez: ustalenie treści w parametrze message określenie parametru template_id definiującego szablon wiadomości Wyższy priorytet ma opcja druga. Definiowanie daty wysyłki System pozwala na określenie daty wysyłki. Jeśli data nie zostanie podana kampania zostanie natychmiastowo dodana do kolejki wysyłek. W przypadku zdefiniowania poprawnego parametru send_date wysyłka zostanie przekazana do realizacji w zaplanowanym terminie. Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego zamówienia kampanii klient otrzyma przykładowo następującą odpowiedź: <asendo username="uzytkownik" action="send"> <order order_id="tta2" send_date="2014-04-02 13:45" price="0.01" created="2014-04-02 13:44:44"> <wait count="1"> <email>obiorca1@asendo.pl</email> </wait> <nosend count="1"> <email reason="konto znajduje się na czarnej liście lub subskrybent nie wyraził zgody na otrzymywanie wiadomości">obiorca2@asendo.pl</email> </nosend> </order> Lub w przypadku wysyłki testowej: <asendo username="test" action="send"> <contact>ok</contact> 33
Objaśnienie poszczególnych sekcji XML <order></order> Zawiera dane dotyczące zapisanej kampanii: order_id identyfikator zamówienia send_date data wysyłki w formacie RRRR-MM-DD GG:MM price koszt kampanii PLN netto created data zamówienia w formacie RRRR-MM-DD GG:MM:SS <wait></wait> Wiadomości dodane do kolejki wysyłek. Atrybuty: count ilość wiadomości dodanych do kolejki <nosend></nosend> <email></email> Wiadomości odrzucone. Atrybuty: count ilość wiadomości odrzuconych Element zawierający informacje dotyczące odbiorcy. W przypadku odrzucenia w atrybucie reason podana jest przyczyna odrzucenia wybranego adresu email 34
7. Pobranie salda Wywołanie adresu Aby przy pomocy Zdalnej obsługi pobrać aktualny stan salda należy przesłać określone zgłoszenie protokołem HTTPS metodą POST lub GET. Przykładowo adres w przeglądarce wyglądać może następująco: /api/email/? username=uzytkownik&password=haslo&action=get_saldo Dostępne parametry Parametr Typ Przykładowa wartość lub format username String username Login użytkownika WebAPI password String Haslo Hasło do konta WebAPI action String get_saldo Aby pobrać stan salda należy umieścić tutaj get_saldo Zwrot odpowiedzi W zależności od przesłanych danych asendo.pl wygeneruje w odpowiedzi dokument w formacie XML z informacją na temat wykonanej akcji. W przypadku prawidłowego pobrania salda klient otrzyma przykładowo następującą informację zwrotną: <asendo username="test" action="get_saldo"> <saldo>88.01</saldo> 35
Objaśnienie poszczególnych sekcji XML <saldo></saldo> Zawiera aktualną wartość salda konta w PLN netto 36
8. Historia zmian Wersja 1.0-20014-05-19 - Pierwsza odsłona zdalnej obsługi APIEmail 37