Ustawienia

Po uruchomieniu systemu Webhooks FreshMail będzie wysłał na wybraną przez Ciebie bramkę URL informacje o zdarzeniach za pomocą żądań typu HTTP POST. Najczęstszym wykorzystaniem tego typu integracji jest monitorowanie zaangażowania odbiorców (kliknięcia oraz otwarcia emaili), synchronizacja wypisanych odbiorców, identyfikowanie odbiorców, którzy nie reagują na Twoje kampanie od wielu miesięcy lub tworzenie zaawansowanej analityki po Twojej stronie.

Konfiguracja

Aby skonfigurować mechanizm WebHooks należy zalogować się do Twojego konta we FreshMail'u, następnie przejść do Ustawienia -> Wtyczki i API -> Webhooks. Pojawi się formularz z pole URL. Po dodaniu URL do Twojej bramki możesz przetestować połączenie. Dla przykładu możemy założyć, że skrypt który chcesz aby był Twoją bramką umieściłeś pod adresem:

               http(s)://my-domain.com/api/freshmail/webhooks

Możliwe błędy

Jeśli zaraz po przetestowaniu połączenia za pomocą przycisku Testuj połączenie otrzymałeś komunikat o błędzie nie przejmuj się. Przecież jeszcze nie umieściłeś w tej lokalizacji żadnego skryptu.

Jeśli fizycznie nie ma tam jeszcze żadnej aplikacji, która mogłaby odpowiadać na nasze żądania po API to w komunikacie błędu pojawi się komunikat z biblioteki CURL w postaci:

Błąd requestu (curl) 404 - HTTP/1.1 404 Not Found

W takim wypadku musimy umieścić skrypt, który obsłuży nasze żądania. Jeśli umieścimy tam jakikolwiek skrypt to komunikat powinien się zmienić na:

Serwer odpowiedział lecz w niepoprawnym formacie

Oznacza to, że sktypt został znaleziony przez naszą aplikację poprawnie, ale niestety nie odpowiada danymi w poprawnym formacie.

Żądania testowe

W pierwszej kolejności należy sprawić, aby Twój skrypt był w stanie obsłużyć żądania testowe. Od nich zaczyna się cała komunikacja. Takie żądania możesz wysłać bezpośrednio z systemu FreshMail korzystając z przycisku Testuj połączenie lub przetestować je samemu np. za pomocą biblioteki CURL:

curl -X POST -d '{"test":"1"}' http(s)://my-domain.com/api/freshmail/webhooksie

FreshMal oczekuje zwrotki o kodzie 2xx HTTP w odpowiedzi na powyższe żądanie. Dodatkowo żądanie testowe musi zwrócić:

{"status":"ok"}

W ten sposób możesz przetestować całą komunikację testową. Jeśli ona dział poprawnie oznacza to, że nie ma żadnych problemów sieciowych w komunikacji pomiędzy serwerami FreshMaila a Twoim serwerem.

Zdarzenia

W produkcyjnej komunikacji będziesz otrzymywał żądania typu HTTP POST zawierające obiekt JSON z tablicą zawierającą kolejne zdarzenia. Każde pojedyncze żądanie może zawierać do 1000 zdarzeń i będzie wysyłane z możliwie najmniejszym opóźnieniem w stosunku do działań które odbiorca wykonuje na mailu.

Przykładowe żądanie HTTP POST

[
    {
        "campaign":"nsqqmsb52q",
        "email":"john.doe@freshmail.com",
        "event":"open",
        "timestamp":1439889386,
        "attempt":1,
        "hash":"97db930155"
    },{
        "campaign":"nsqqmsb52q",
        "email":"john@freshmail.com",
        "event":"unsubscribe",
        "timestamp":1439889404,
        "attempt":1,
        "hash":"ccec7ad7f1"
    },{
        "campaign":"nsqqmsb52q",
        "email":"antonio@freshmail.com",
        "event":"open",
        "timestamp":1439889604,
        "attempt":1,
        "hash":"324f4075a6"
    },{
        "campaign":"nsqqmsb52q",
        "email":"samuel@freshmail.pl",
        "event":"open",
        "timestamp":1439892486,
        "attempt":1,
        "hash":"9d041d9ab3"
    }
]

Typy zdarzeń

Poniżej znajduje się lista wszystkich obsługiwanych przez FreshMaila zdarzeń:

Zdarzenie Uwagi
Open Odbiorca otworzył treść HTML
Click Odbiorca kliknął w link w wiadomości
Unsubscribe Odbiorca kliknął w link rezygnacji w wiadomości

Parametry domyślne zdarzeń

Każde zdarzenie posiada zestaw obligatoryjnych parametrów, które zawsze są przesyłane w tablicy ze zdarzeniem:

Właściwość Typ Uwagi
event String Typ zdarzenia (opisany powyżej)
campaign String Hash kampanii w której nastąpiła akcja (10 znaków)
timestamp Integer Czas w którym nastąpiło zdarzenie (w formie Unixowego znacznika czasu)
attempt Integer Ilość prób dostarczenia danego zdarzenia
hash String Identyfikator zdarzenia (od 10 do 50 znaków)

Identyfikator zdarzenia jest wykorzystywany do potwierdzenia odbioru.

UWAGA! Identyfikator NIE jest unikalny.

Jeśli dwa zdarzenia posiadają ten sam znacznik oznacza to, że niosą one dokładnie tą samą informację. Dla przykładu jeśli dany użytkownik otworzy daną kampanię 2 razy w przeciągu paru sekund to identyfikatory tego zdarzenia będą różne bo czas otwarcia będzie się różnił. Jeśli natomiast użytkownikowi udałoby się otworzyć maila 2 razy w tej samej sekundzie to identyfikatory dla tych dwóch zdarzeń będą identyczne, bo będą niosły dokładnie są samą informacje i z punktu FreshMail Webhooks będą nie rozróżnialne.

Parametry poszczególnych zdarzeń

Poniższa sekcja pokazuje przykład każdego typu zdarzenia. Pamiętaj, że każde zdarzenie jest pojedynczym elementem tablicy, która jest przesyłana w HTTP POST. Pola w zdarzeniach mogą pojawiać się w różnej koleności i nie są w żaden sposób sortowane.

Otwarcie

Zdarzenie mówiące o tym, że odbiorca otworzył wiadomość HTML.

{
    "campaign":"campaign_hash",
    "email":"email@example.com",
    "event":"open",
    "timestamp":1439892486,
    "attempt":1,
    "hash":"event_id"
}

Kliknięcie

Zdarzenie mówiące o tym, że odbiorca kliknąl w link w mailu.

{
    "campaign":"campaign_hash",
    "email":"email@example.com",
    "event":"click",
    "timestamp":1439971916,
    "attempt":1,
    "hash":"event_id",
    "url":"http://your-link.com/blog/"
}

Wypisanie

Zdarzenie mówiące o tym, że odbiorca skorzystał z linku rezygnacji w mailingu.

{
    "campaign":"campaign_hash",
    "email":"email@example.com",
    "event":"unsubscribe",
    "timestamp":1439889404,
    "attempt":1,
    "hash":"event_id"
}

Potwierdzenie odbioru

Każde żądanie musi zostać potwierdzone, aby FreshMail wiedział, że zdarzenia zostały poprawnie przyjęte. W odpowiedzi oczekujemy kodu HTTP 200 oraz tablicy JSON z potwierdzonymi poszczególnymi zdarzeniami. Takie żądanie powinno zawierać tablicę z poszczególnymi zdarzeniami zawierającą:

Pole Typ Wartość
hash String Hash zdarzenia które potwierdzasz
status Boolean Wartość czy odbiorów danego zdarzenia jest potwierdzony czy nie

Dla przykładu takie potwierdzenie może wyglądać jak w przykładzie poniżej. Żądanie wysyłane z FreshMail'a:

[
    {
        "campaign":"nsqqmsb52q",
        "email":"john.doe@freshmail.com",
        "event":"open",
        "timestamp":1439889386,
        "attempt":1,
        "hash":"97db930155"
    },{
        "campaign":"nsqqmsb52q",
        "email":"john@freshmail.com",
        "event":"unsubscribe",
        "timestamp":1439889404,
        "attempt":1,
        "hash":"ccec7ad7f1"
    }
]

Poprawna odpowiedź (kod HTTP 200):

[
    {
      "hash":"97db930155",
      "status":true
    },{
      "hash":"ccec7ad7f1",
      "status":true
    }
]