További dokumentációk

Fel és leiratkozás

2022.11.02 — Posted by Webb & Flow

Tartalomjegyzék

Előfeltételek

Minden API végpont hívásához a megfelelő service account adatait kell megadni az authentikációban, az email küldő API-val azonos módon.

Műveletek eredménye

Minden művelet egy numerikus válasz kóddal jelzi az eredményt:

  • 0: SUCCESS: sikeres művelet
  • 1: ERROR: rossz projekt
  • 2: ERROR: invalid validáló kód (api esetén nem fordul elő)
  • 3: ERROR: validálandó email cím nem létezik
  • 4: ERROR: nincs email cím megadva
  • 5: ERROR: nincs email list azonosító megadva, vagy az nem létezik
  • 6: ERROR: invalid email cím
  • 7: WARNING: részben sikeres művelet, de email validálás szükséges
  • 8: SUCCESS: sikeres művelet, de át kell irányítani valahova
  • 9: WARNING: részben sikeres művelet, de email validálás szükséges és át kell irányítani valahova
  • 10: ERROR: robot check hiba (api esetén nem fordul elő)
  • 11: ERROR: referer hiba (api esetén nem fordul elő)
  • 20: ERROR: egyéb hiba (api esetén elvileg nem fordul elő)
  • 30: ERROR: az email profil törlés alatt áll (nem lehet feliratkoztatni sehova, amíg az aktuális törlési folyamat nem végzett)
  • 31: ERROR: az email lista törlés alatt áll (már nem lehet új email címet feliratkoztatni rá)
  • 90: ERROR: már fel van iratkozva az adott email listára
  • 99: ERROR: az email cím blacklist-re van rakva (vagy globálisan, vagy az adott email listán)

Email listára feliratkozás

Az email feliratkozás a POST https://app.forwardhub.com/client/emailList/{EMAILLISTID}/subscribe végponton érhető el, ahol az {EMAILLISTID} az az email lista, amire fel kell iratkoztatni az adott email címet.

A Request body tartalma:

{
   "email":"user@example.com",
   "source": "a",
   "personalData": {
       "data1":1234,
       "data2":"data2value"
   }
}
  • email
    • az email cím, amit fel kell iratkoztatni
    • kötelező
  • source
    • a feliratkozás forrása
    • opcionális
    • lehetséges értékek:
      • a
        • api
      • m (default)
        • manual
  • personalData
    • személyes adatok az email profilhoz
    • opcionális
    • key-value párosok

A feliratkozás során ugyanazok a folyamatok indulnak el a ForwardHub-ban, mintha ott iratkozna fel a felhasználó.

  • source = m esetén azonos az űrlapon való feliratkozással
    • amennyiben a ForwardHub még nem ismeri az email címet, vagy az még nics validálva, és az email lista megköveteli az email cím validálását, a feliratkozás nem történik meg automatikusan, hanem kap a felhasználó egy email-t, amiben egy, a ForwardHub-ra mutató validáló link van
      • a validálás pillanatában az addig várakozó feliratkozások megtörténnek, így nem kell azokat újra küldeni
    • már validált email cím esetén automatikusan feliratkozik az email listára
  • source = a esetén azonos a ForwardHubn felületen való importálással
    • automatikusan validáltnak minősül az email cím és feliratkozik az email listára

Válasz:

{
   "email": "user@example.com",
   "emailListId": "5649205632696320",
   "emailList": "list 3",
   "result": 0,
   "redirect": null
}
  • email
    • a kapott email cím
  • emailListId
    • a kapott email list azonosító
  • emailList
    • az email lista neve, amennyiben létezik
  • result
    • a művelet eredménye
  • redirect
    • amennyiben a felületen végezné el a műveletet és a beállítások szerint át kellene valahova irányítani, ebben a mezőben szerepel az url

Email cím validálás

Amennyiben szükséges, a felhasználó helyett lehet validálni az email címet a PATCH https://app.forwardhub.com/client/emailList/verify végponton.

A Request body tartalma:

{
   "email":"user@example.com",
}
  • email
    • az email cím, amit validálni kell
    • kötelező

Az API-n keresztüli validáláshoz nem szükséges az eredetileg generált validáló token-t küldeni.

Válasz:

{
   "email": "user@example.com",
   "result": 0
}

A művelet akkor is result = 0 választ ad, ha az email cím már validálva van.

Leiratkozás email listáról

Az email leiratkozás a DELETE https://app.forwardhub.com/client/emailList/{EMAILLISTID}/unsubscribe végponton érhető el.

Az url-ben query paraméterként a következő paramétereket lehet küldeni (mivel a DELETE műveletnek nem lehet request body-ja):

  • email
    • az email cím, amit le kell iratkoztatni
    • kötelező
  • source
    • a leiratkozás forrása
    • opcionális
    • lehetséges értékek:
      • a
        • api
      • m (default)
        • manual

A leiratkozás során ugyanazok a folyamatok indulnak el a ForwardHub-ban, mintha ott iratkozna le a felhasználó.

Válasz:

{
   "email": "user@example.com",
   "emailListId": "5649205632696320",
   "emailList": "list 3",
   "result": 0,
   "redirect": null
}
  • email
    • a kapott email cím
  • emailListId
    • a kapott email list azonosító
  • emailList
    • az email lista neve, amennyiben létezik
  • result
    • a művelet eredménye
  • redirect
    • amennyiben a felületen végezné el a műveletet és a beállítások szerint át kellene valahova irányítani, ebben a mezőben szerepel az url

A művelet akkor is result = 0 választ ad, ha az email cím nincs feliratkozva az adott email listára.

Leiratkozás minden email listáról

A tömeges email leiratkozás a DELETE https://app.forwardhub.com/client/emailList/unsubscribeFromAll végponton érhető el.

Az url-ben query paraméterként a következő paramétereket lehet küldeni (mivel a DELETE műveletnek nem lehet request body-ja):

  • email
    • az email cím, amit le kell iratkoztatni
    • kötelező
  • source
    • a leiratkozás forrása
    • opcionális
    • lehetséges értékek:
      • a
        • api
      • m (default)
        • manual

A rendszer az összes olyan email listáról leiratkoztatja az email címet, amin aktuálisan fel van iratkozva.

A leiratkozás(ok) során ugyanazok a folyamatok indulnak el a ForwardHub-ban, mintha ott iratkozna le a felhasználó.

Válasz:

[
   {
       "email": "user@example.com",
       "emailListId": "5642368648740864",
       "emailList": "list 1",
       "result": 0,
       "redirect": null
   },
   {
       "email": "user@example.com",
       "emailListId": "5653784671813632",
       "emailList": "list 2",
       "result": 0,
       "redirect": null
   }
]

A válaszban egy listát ad vissza, ahol egy elem ugyanaz, mint a leiratkozás API esetén, és az adott email listáról leiratkozás eredményét adja vissza.

Feliratkozások lekérése

Egy email cím feliratkozásait a GET https://app.forwardhub.com/client/emailList/subscriptions végponton lehet lekérni.

Az url-ben query paraméterként a következő paramétereket lehet küldeni (mivel a DELETE műveletnek nem lehet request body-ja):

  • email
    • az email cím, amit le kell iratkoztatni
    • kötelező
  • all
    • 0 vagy 1 (default 0)
    • 1 esetén az inaktív feliratkozások is látszódnak (azok az email listák, amikre korábban fel volt iratkozva, de már nincs)

Figyelem: amennyiben az adott email cím validálásra vár, és emiatt a feliratkozása(i) várakozási sorba került(ek), ez(ek) nem kérhetők le az API-ról ez a lista csak azokat az email listákat tartalmazza, amihez az adott email címnek köze volt, azokat nem, amikre soha nem volt még feliratkozva

Válasz:

[
   {
       "email": "user@example.com",
       "emailListId": "5642368648740864",
       "emailList": "list 1",
       "startDate": "2021-05-04T10:51:33+00:00",
       "endDate": null,
       "active": 1
   },
   {
       "email": "user@example.com",
       "emailListId": "5643677540024320",
       "emailList": "list 5",
       "startDate": "2021-01-15T12:57:45+00:00",
       "endDate": null,
       "active": 1
   },
   {
       "email": "user@example.com",
       "emailListId": "5653784671813632",
       "emailList": "list 2",
       "startDate": "2020-09-02T12:02:45+00:00",
       "endDate": null,
       "active": 1
   }
]

A válaszban egy lista található az email listákkal és a feliratkozás dátumaival. Egy elem struktúrája:

  • email
    • a kapott email cím
  • emailListId
    • az adott email lista azonosítója
  • emailList
    • az adott email lista neve, amennyiben létezik
    • ha az értéke null, és nem aktív a feliratkozás, akkor az adott email lista már törölve lett
  • startDate
    • a feliratkozás ideje (ha többször fel és le iratkozott, akkor az utolsó ideje)
  • endDate
    • a leiratkozás ideje (ha többször fel és le iratkozott, akkor az utolsó ideje)
    • null, ha aktív a feliratkozás
  • active
    • 1, ha aktív, 0, ha inaktív

Válasz, ha az inaktívak is le vannak kérve:

[
   {
       "email": "user@example.com",
       "emailListId": "5629654941564928",
       "emailList": null,
       "startDate": "2020-08-04T10:15:44+00:00",
       "endDate": "2020-08-25T14:37:58+00:00",
       "active": 0
   },
   {
       "email": "user@example.com",
       "emailListId": "5642368648740864",
       "emailList": "list 1",
       "startDate": "2021-05-04T10:51:33+00:00",
       "endDate": null,
       "active": 1
   },
   {
       "email": "user@example.com",
       "emailListId": "5643677540024320",
       "emailList": "list 5",
       "startDate": "2021-01-15T12:57:45+00:00",
       "endDate": null,
       "active": 1
   },
   {
       "email": "user@example.com",
       "emailListId": "5649205632696320",
       "emailList": "list 3",
       "startDate": "2021-05-21T12:55:24+00:00",
       "endDate": "2021-05-21T13:22:56+00:00",
       "active": 0
   },
   {
       "email": "user@example.com",
       "emailListId": "5653784671813632",
       "emailList": "list 2",
       "startDate": "2020-09-02T12:02:45+00:00",
       "endDate": null,
       "active": 1
   },
   {
       "email": "user@example.com",
       "emailListId": "5680529164730368",
       "emailList": null,
       "startDate": "2020-08-07T14:13:30+00:00",
       "endDate": "2020-08-25T14:45:16+00:00",
       "active": 0
   }
]