Newsletter – API v1 and v2

Wprowadzenie do Newsletter API v1 i v2

Newsletter API, w wersji 1 i 2, to potężne narzędzie, które umożliwia zintegrowanie systemów z wtyczką Newsletter. Dzięki tym API możemy zarządzać subskrybentami, ich danymi oraz interakcjami bezpośrednio z aplikacji zewnętrznych. Wersja 2 API oferuje więcej funkcji i elastyczności, dlatego zaleca się migrację z wersji 1, która mimo że wciąż jest obsługiwana, nie jest tak rozwinięta jak jej następca.

Kluczowe elementy Newsletter API v1 i v2

Podstawowe informacje o autoryzacji

Aby korzystać z większości wywołań API, konieczne jest uzyskanie klucza autoryzacyjnego. Klucz ten zapewnia, że tylko autoryzowane aplikacje mogą wykonywać żądania do API. Ważne jest, aby klucz ten był przechowywany bezpiecznie i nie był wykorzystywany w klientach publicznych ze względów bezpieczeństwa.

Dodawanie subskrybenta do bloga

Jednym z podstawowych zastosowań API jest możliwość dodawania subskrybentów. Aby dodać nowego subskrybenta, należy użyć endpointu subscribers z metodą POST. Do żądania należy dołączyć obiekt JSON zawierający dane subskrybenta, przy czym adres e-mail jest jedynym wymaganym polem. Jeśli subskrybent o podanym adresie e-mail już istnieje, nie nastąpi zmiana, a żądanie zwróci błąd. Proces ten jest bezproblemowy i wymaga jedynie zapewnienia, że dane pochodzą z wiarygodnego źródła.

Aktualizacja istniejącego subskrybenta

Jeśli chcesz zaktualizować dane subskrybenta, użyj endpointu subscribers z metodą PUT. Można podać identyfikator subskrybenta (ID) lub adres e-mail. Wszelkie podane dane zastąpią aktualne wartości w systemie. Metoda ta pozwala również na aktualizację list oraz pól prywatnych, pod warunkiem, że uwzględnisz także klucz uwierzytelniający.

Dodawanie lub aktualizowanie subskrybenta w jednym wywołaniu

Możliwe jest dodawanie lub aktualizowanie subskrybenta w jednym wywołaniu, co przyspiesza i upraszcza proces integracji. Użycie metody PUT endpointu subscribers pozwala na wygodne zarządzanie danymi subskrybentów.

Zmiana statusu subskrybenta

Istnieje możliwość zmiany statusu subskrybenta na taki jak „odrzucony”, „wypisany” itp. Osiągamy to poprzez użycie metody PUT i podanie identyfikatora subskrybenta lub adresu e-mail oraz nowego statusu. W przypadku nieobecności takiego subskrybenta w systemie, zostanie on dodany z nowym identyfikatorem.

Dodawanie subskrybenta do konkretnych list

Gdy subskrybent działa w sposób, który powinien skojarzyć go z określoną listą, możemy użyć metody PUT endpointu subscribers. Należy przy tym pamiętać, żeby podać identyfikator subskrybenta lub adres e-mail oraz informacje o liście, do której chcemy dodać lub z której chcemy usunąć subskrybenta.

Usuwanie subskrybenta z bazy danych

Aby trwale usunąć subskrybenta, można skorzystać z metody DELETE na endpointcie subscribers. Ten proces całkowicie usuwa wszystkie dane subskrybenta z systemu. Po tej operacji nie powinna pozostać żadna informacja o danym subskrybencie. Warto zauważyć, że usunięcie subskrybenta różni się od zmiany statusu na „wypisany”, która pozwala zachować dane.

Rozpoczęcie standardowego procesu subskrypcji

Endpoint subscriptions z metodą POST można wykorzystać do rozpoczęcia standardowego procesu subskrypcji. Wymaga to jedynie adresu e-mail. Ten proces, w odróżnieniu od samego dodawania subskrybenta, uruchamia szereg mechanizmów, takich jak weryfikacja poprawności danych i wysyłanie wiadomości powitalnych, w zależności od ustawień opt-in.

Obsługa anulowania subskrypcji

Aktualnie API nie obsługuje bezpośredniego procesu anulowania subskrypcji. Należy umożliwić subskrybentom samodzielne anuluowanie subskrypcji poprzez link w newsletterze. Możliwe jest jednak zdalne zmienienie statusu subskrybenta na „wypisany” korzystając z odpowiedniego endpointu.

Zmiana danych profilu subskrybenta

API nie umożliwia subskrybentowi zmiany swoich danych bezpośrednio z poziomu klienta publicznego. Kolejnym krokiem, który można podjąć, jest implementacja rozwiązania na poziomie serwera, wykorzystującego endpoint subscribers. Podobnie jak wcześniej, należy zachować ostrożność, ponieważ ten endpoint wymaga uwierzytelnienia.

Uzyskiwanie dostępnych list subskrypcyjnych

Chcąc uzyskać listę skonfigurowanych list subskrypcyjnych, można użyć endpointu lists z metodą GET. Ta operacja zwraca wszystkie listy dostępne w systemie, zarówno publiczne, jak i prywatne, pod warunkiem podania odpowiedniego klucza API.

Otrzymywanie informacji o ostatnich newsletterach

Jeżeli zależy nam na pozyskaniu informacji o ostatnich wysłanych newsletterach, powinniśmy skorzystać z endpointu newsletters. Umożliwia to pobranie danych o ostatnich 10 wysłanych newsletterach i stworzenie archiwum. Należy przy tym zauważyć, że newslettery, które są w trakcie wysyłania, w wersji roboczej albo zaplanowane na później, nie będą zwracane.

Testowanie API lokalnie

W celu testowania API na lokalnym serwerze bez HTTPS, można dodać odpowiedni kod do pliku wp-config.php. Warto jednak pamiętać, że pozwolenie na połączenia bez HTTPS oznacza, że klucze autoryzacyjne nie będą szyfrowane, co stanowi poważne ryzyko dla bezpieczeństwa.

Podsumowanie

Newsletter API w wersjach 1 i 2 stanowi niezwykle użyteczne narzędzie, które pozwala na efektywne zarządzanie subskrybentami oraz ich danymi. Wersja 2 API oferuje szereg funkcji, które zwiększają elastyczność i możliwości integracji z zewnętrznymi systemami. Zachęca się do migracji na nowszą wersję, aby w pełni wykorzystać potencjał, który daje nowoczesna technologia. Dzięki zastosowaniu odpowiednich endpointów oraz kluczy autoryzacyjnych, możliwe jest zautomatyzowanie wielu procesów oraz zapewnienie dużej efektywności działań marketingowych.