Webhooki Email API&SMTP

Aby otrzymywać informacje o wybranych zdarzeniach związanych z wiadomościami wysłanymi poprzez API v3 lub SMTP, w pierwszej kolejności należy je zasubskrybować przy pomocy prostego zapytania:

1
2
3
4
5
6
7
8
9

POST https://api.freshmail.com/v3/webhook/subscriptions
Authorization: Bearer [BEARER]
Content-Type: application/json;charset=UTF-8

{
  "address": "ADRES",
  "type": "TYP",
  "module": "MODUŁ"
}

Pole module

- transactional_email - moduł związany z wiadomościami Email API&SMTP

Pole type

- open - otwarcie wiadomości

- click - kliknięcie w link wysłany w wiadomości

- bounce - odbicie wiadomości

Pole address

Pole z adresem, na który zostanie wysłana informacja o danym zdarzeniu.

Odpowiedź

Serwer odpowie prostą tablicą JSON z hashem subskrypcji.

1

{"id": "HASH"}

Zwracanie wszystkich webhooks

Request

1
2

GET https://api.freshmail.com/v3/webhook/subscriptions
Authorization: Bearer [BEARER]

Przykładowa odpowiedź

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

[
  {
    "id": "zN",
    "address": "localhost",
    "active": false,
    "type": "click",
    "module": "transactional_email"
  },
  {
    "id": "RW",
    "address": "localhost",
    "active": true,
    "type": "open",
    "module": "transactional_email"
  }
]

Edycja subskrypcji

Dostępne pola

Wymagane dane

- module - moduł z jakiego chcemy dostawać informacje o zdarzeniach

Opcjonalne pola

- address - adres na jaki informacja jest wysyłana

- active - flaga oznaczająca czy dana subskrypcja jest aktywna

- type - typ akcji na jaki ma reagować

Przykładowy request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

PUT https://api.freshmail.com/v3/webhook/subscriptions/{HASH}
Authorization: Bearer [BEARER]
Content-Type: application/json;charset=UTF-8

{
  "address": "localhost",
  "active": 0,
  "type": "click",
  "module": "transactional_email"
}

Przykładowa odpowiedź

1

{"success": true}

Zwrócenie informacji o konkretnej subskrypcji

1
2

GET https://api.freshmail.com/v3/webhook/subscriptions/{HASH}
Authorization: Bearer [BEARER]

Wymagane pole

- {HASH} - hash subskrypcji

Odpowiedź

1
2
3
4
5
6
7

{
  "id": "5m",
  "address": "localhost",
  "active": true,
  "type": "open",
  "module": "transactional_email"
}

Usuwanie webhook

1
2

DELETE https://api.freshmail.com/v3/webhook/subscriptions/[ID WEBHOOK]
Authorization: Bearer [BEARER]

Wymagane pole

- {HASH} - hash subskrypcji

Odpowiedź

1

{"success": true}

Testowanie webhook

Przygotowaliśmy możliwość przetestowania webhooków. Wystarczy wysłać odpowiednie zapytanie i otrzymamy przykładową informację na wzkazany adres.

Request

1
2
3
4
5
6
7
8
9

POST https://api.freshmail.com/v3/webhook/notificationTest/
Authorization: Bearer [BEARER]
Content-Type: application/json;charset=UTF-8

{
  "address": "localhost",
  "type": "click",
  "module": "transactional_email"
}

Odpowiedź

1

{"success": true}

Struktura webhook

Każdy z webhooków ma swoją strukturę, zależną od jego typu:

Moduł transactional_email

Typ open

1
2
3
4
5
6
7
8

{
  "module": "transactional_email",
  "name": "open",
  "messageId": "03.02.02.aaaaa.1245...",
  "ip": "127.0.0.1",
  "time": 1618996547,
  "version": 1
}

Typ click

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  "module": "transactional_email",
  "name": "click",
  "messageId": "03.02.02.aaaaa.1245...",
  "ip": "127.0.0.1",
  "userAgent": "Mozilla/5.0 ...",
  "url": "https://www.freshmail.pl",
  "time": 1618996547,
  "version": 1
}

Typ bounce

1
2
3
4
5
6
7
8
9

{
  "module": "transactional_email",
  "name": "bounce",
  "messageId": "03.02.02.aaaaa.1245...",
  "type": "hard",
  "reason": "reason ...",   
  "time": 1618996547,
  "version": 1
}

Co oznaczają poszczególne pola w strukturze webhook

module

Aktualnie jest to zawsze transactional_email - dotyczy to wysyłki Email API i SMTP przy pomocy api v3

name

Nazwa zdarzenia. Aktualnie są dostępne: - open - otwarcie maila - click - kliknięcie w link znajdujący się w wiadomości mail - bounce - odbicie wiadomości

messageId

Unikalny identyfikator określający jakiej wiadomości dotyczy informacja

ip

IP odbiorcy maila (ta informacja znajduje się tylko w click i open)

userAgent

Klient pocztowy za pomocą jakiego została otwarta wiadomość mail (ta informacja znajduje się tylko w click i open)

url

Adres, w który kliknięto (ta informacja tylko w click)

time

Czas zdarzenia

reason

Odpowiedź serwera w przypadku odbicia wiadomości mail (ta informacja znajduje się tylko w bounce)

type

Określa typ odbicia wiadomości mail - może przyjąć dwie wartości: hard, soft (ta informacja znajduje się tylko w bounce)

version

Określa wersję webhook