FreshMail — jak używać: integracje

FreshMail API pozwala połączyć aplikację napisaną w PHP z kontem FreshMail i obsługiwać dane oraz kampanie przez żądania API.
Ten poradnik prowadzi przez uwierzytelnianie, pracę z subskrybentami i uruchamianie wysyłki. Pokazuje też, jak odczytywać odpowiedzi i rozpoznawać błędy integracji. Dokumentacja REST API v2 opisuje 6 operacji dotyczących pojedynczych subskrybentów oraz 5 operacji dotyczących kampanii¹.

Jak skonfigurować dostęp do FreshMail API i uwierzytelnić żądania w PHP?

Zanim aplikacja PHP wyśle żądanie do FreshMail API, przygotuj dane dostępowe konta. Następnie skonfiguruj uwierzytelnianie według schematu z dokumentacji.
W wariancie opartym na kluczu i podpisie żądanie musi zawierać 2 nagłówków: X-Rest-ApiKey i X-Rest-ApiSign¹.

Na koncie FreshMail znajdź API key, który identyfikuje dostęp do API, oraz powiązany z nim API secret. Umieść oba w konfiguracji środowiska, nie w kodzie dostępnym publicznie.
Ten sposób uwierzytelniania wymaga przechowywania 2 odrębnych danych: API key i API secret¹.

Klient PHP powinien wysyłać żądania przez HTTPS i dołączać dane uwierzytelniające zgodnie z dokumentacją FreshMail API. Sekretu nie wpisuj ani do adresu żądania, ani do treści strony internetowej.
Połączenie HTTPS domyślnie korzysta z portu 443².

Po konfiguracji klient PHP dołącza dane dostępowe do żądań. API secret pozostaje poza publicznym kodem aplikacji³.

Jak dodawać i aktualizować subskrybentów przez FreshMail API w PHP?

Przez FreshMail API aplikacja PHP może przekazać dane subskrybenta do wybranej listy mailingowej, czyli zbioru odbiorców kampanii.
Aby dodać pojedynczy kontakt, podaj 1 identyfikatora listy: jej hash w polu „list”⁴.

• Wybór listy mailingowej wskazuje zbiór odbiorców, którego ma dotyczyć żądanie aplikacji PHP.
• Przygotowanie danych subskrybenta obejmuje adres e-mail i informacje przekazywane do FreshMail. Dane nowego kontaktu oddziel od zmian w istniejącym kontakcie.
• Dodanie subskrybenta wymaga wysłania z PHP żądania dla nowego kontaktu według schematu FreshMail API.
• Aktualizacja subskrybenta wymaga wskazania istniejącego kontaktu i przekazania zmienionych danych według schematu FreshMail API.

Aplikacja PHP obsługuje dodanie i aktualizację przez 2 odrębne operacje⁴:

Jak uruchomić wysyłkę kampanii FreshMail przez API w PHP?

Aplikacja PHP uruchamia wysyłkę przygotowanej kampanii żądaniem opisanym w dokumentacji używanej wersji FreshMail API. Najpierw wskaż kampanię i jej odbiorców.
Żądanie campaigns/send wymaga 1 identyfikatora kampanii: jej hasha¹.

• Kampania FreshMail powinna mieć gotowy temat, nadawcę i treść wiadomości. Sprawdź je przed uruchomieniem wysyłki.
• Odbiorcy kampanii powinni należeć do zamierzonej grupy. Zweryfikuj listę mailingową lub segment, czyli część odbiorców wyodrębnioną według określonych kryteriów.
• Żądanie wysyłki przygotuj w PHP według metody i pól podanych w dokumentacji FreshMail API. Przekaż identyfikator właściwej kampanii.
• Odpowiedź API zapisz w aplikacji PHP, by odróżnić przyjęcie żądania od błędu. Przyjęcie żądania nie potwierdza dostarczenia wiadomości odbiorcom.

Wysyłkę uruchamia żądanie dotyczące przygotowanej kampanii. Wynik tego żądania aplikacja odczytuje z odpowiedzi API.
Dokumentacja podaje kod HTTP 200 dla żądania zakończonego bez błędu¹.

Jak przetestować integrację PHP i rozpoznać błędy odpowiedzi API?

Integrację PHP z FreshMail API przetestuj kontrolowanym żądaniem. Osobno przeanalizuj połączenie, status HTTP i treść odpowiedzi API.
Dzięki temu ustalisz, czy błąd dotyczy przesyłania danych, uwierzytelniania, czy wykonania operacji.

• Żądanie testowe skieruj do operacji, której wynik zweryfikujesz bez rzeczywistej wysyłki. Zapisz typ operacji i czas jej wykonania.
• Połączenie HTTP oceń na podstawie wyniku klienta PHP. Błąd połączenia odróżnij od odpowiedzi serwera na dostarczone żądanie⁵.
• Status odpowiedzi odczytaj przed sprawdzeniem jej treści. Samo otrzymanie odpowiedzi nie oznacza jeszcze, że FreshMail wykonał operację.
• Treść odpowiedzi API porównaj ze strukturą opisaną w dokumentacji używanej wersji. Zapisz komunikat błędu i identyfikator operacji, jeśli odpowiedź go zawiera.
• Dziennik aplikacji prowadź bez zapisywania sekretów dostępowych i pełnych danych subskrybentów. Połącz wpis o żądaniu z wpisem dotyczącym odpowiedzi.

Zestawienie wyniku połączenia, statusu HTTP i treści odpowiedzi API pomaga wskazać miejsce błędu.
Zakresy kodów HTTP mają następujące znaczenie⁶:

Do czego jeszcze służy FreshMail API w integracji z PHP?

FreshMail API może też połączyć witrynę WordPress z kontem FreshMail. Zapisy zbiera wówczas wtyczka FreshMail For WordPress.
Aby ją połączyć, wpisz klucz API i sekret API w zakładce „FreshMail > Connect with FreshMail”⁷.

FreshMail For WordPress pozwala dodać pole zapisu na listę do wybranego formularza WordPress, na przykład formularza komentarzy⁷. Wtyczka zawiera również FreshMail Widget, który wyświetla formularz w obszarze widżetów, takim jak pasek boczny⁷.
Opis wtyczki wskazuje 2 sposoby udostępnienia zapisu⁸:

Poniższa tabela zestawia minimalne wersje WordPress i PHP wymagane przez FreshMail For WordPress.
Opis wtyczki podaje minimalną wymaganą wersję PHP 5.3⁸.

Dane w tabeli: 7

Podczas konfiguracji pola zapisu wybierz co najmniej 1 listy FreshMail⁷.
Integracja skieruje na nią zapisy z wybranego formularza lub widżetu WordPress.

Najczęściej zadawane pytania

Jaki zakres operacji opisuje REST API v2 FreshMail?

Dokumentacja opisuje 6 operacji dotyczących pojedynczych subskrybentów i 5 dotyczących kampanii.

Jaki port domyślnie wykorzystuje połączenie HTTPS?

HTTPS domyślnie korzysta z portu 443.

Czym różni się lista mailingowa od segmentu?

Lista mailingowa to zbiór odbiorców, a segment — część odbiorców wyodrębniona według określonych kryteriów.

Jakie minimalne wersje WordPressa i PHP podano dla wtyczki FreshMail For WordPress?

Wymagane minimum to WordPress 3.0 i PHP 5.3.

Czy pole zapisu we wtyczce można skonfigurować bez wskazania listy FreshMail?

Nie. Podczas konfiguracji pola zapisu trzeba wybrać co najmniej jedną listę FreshMail.