További dokumentációk

Kiküldött levelek lekérése

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.

Email listázás

Az email-ek listáját a GET https://app.forwardhub.com/client/emails végponton lehet elérni.

Ennél az API-nál lehetséges egyszerre több címzett leveleit együtt lekérve, ami így egy összefűzött listát ad vissza.

A kérést különböző query paraméterekkel lehet szűkíteni.

Kötelező paraméterek (az egyik kell csak):

  • target
    • a levél címzettje
  • targets
    • a levelek címzettjei, ha egyszerre több címzett leveleire vagyunk kíváncsiak
  • targetList
    • a levelek címzettjei, több cím esetén egy string-ben, vesszővel elválasztva

Ha több mező is meg van adva, akkor a targetList mező felülírja a targets mező tartalmát, de a target mező felülírja mindkettőt és csak azt az egy címzettet adja vissza.

Opcionális paraméterek:

  • status
    • milyen státuszú leveleket adjon vissza
    • default: transferred
    • lehetőségek:
      • transferred
        • az SMTP szolgáltatónak elküldött levelek
      • outbox
        • a küldésre váró levelek
      • sent
        • az SMTP szolgáltató által visszaigazoltan kiküldött levelek
      • opened
        • a címzett által megnyitott levelek
      • notopened
        • a címzett által még meg nem nyitott, de már transferred státuszú levelek
      • softBounced
        • a soft bounced levelek
      • hardBounced
        • a hard bounced levelek
      • clicked
        • a címzett által lekattintott levelek
      • spam
        • a spam-nek jelölt levelek
      • rejected
        • az SMTP szolgáltató által visszautasított, ki nem küldött levelek
  • from
    • melyik naptól adja a listát
    • ennek a napnak a 00:00:00 órájától kéri le az adatokat
  • to
    • melyik napig adja a listát
    • az előző nap 23:59:59-ig kéri le az adatokat
  • pageSize
    • egy listában hány elem jelenjen meg
    • default 10
    • max 1000 lehet
  • start
    • lapozás esetén a token, amivel a következő lapot lehet lekérni

A visszaadott levelek dátum szerint csökkenő sorrendben vannak rendezve. outbox esetén ez az levél létrehozásának (pl API hívás) ideje, minden más státusz esetén a transfer date (azaz az SMTP szolgáltató felé küldés ideje).

A rendszer működése miatt az API nem tudja visszaadni, hogy összesen hány elem felel meg a keresésnek, így azt sem tudja megmondani, hogy hány oldalból áll a lista, illetve nem tud konkrét oldalra ugrani. A visszaadott token alapján egy következő kérésnél a következő szeletét lehet lekérni a listának. Fontos, hogy amennyiben megváltozik bármilyen keresési feltétel, a token invaliddá válik, és a tokeneknek van lejárati ideje (általában 1 óra), így nem érdemes permanens módon tárolni.

Amennyiben egy elemnek van csatolmánya, az információkat visszaaadja az API, de a fájlok tartalmát nem, ehhez le kell tölteni a konkrét levelet.

Példa:

GET https://app.forwardhub.com/client/emails?target=user@example.com

vagy

GET https://app.forwardhub.com/client/emails?targets[]=user@example.com

vagy több címzettel

GET https://app.forwardhub.com/client/emails?targets[]=user@example.com&targets[]=user2@example.com

( indexelni is lehet a lista elemeket: GET https://app.forwardhub.com/client/emails?targets[0]=user@example.com&targets[1]=user2@example.com )

vagy egy string-ként küldve

GET https://app.forwardhub.com/client/emails?targetList=user@example.com,user2@example.com

{
   "items": [
       {
           "id": "6679963222671360",
           "target": "user@example.com",
           "type": "sys",
           "templateId": "5764518391054336",
           "emailListId": null,
           "emailListDay": null,
           "emailListTimed": null,
           "params": [],
           "priority": 1,
           "cause": "send via API",
           "batch": null,
           "realTarget": null,
           "debugLevel": 0,
           "subject": "teszt email",
           "createdAt": "2021-03-05T10:10:29+00:00",
           "attachments": [
               {
                   "id": "0",
                   "name": "file1.txt",
                   "type": "text/plain",
                   "size": "15"
               },
               {
                   "id": "1",
                   "name": "file2.txt",
                   "type": "text/plain",
                   "size": "15"
               },
               {
                   "id": "2",
                   "name": "ugyfeltajekoztato-210215.pdf",
                   "type": "application/pdf",
                   "size": "76617"
               }
           ],
           "from": "test1-wnftest-com@forwardhub.com",
           "sender": "Test 1",
           "replyTo": "test1-wnftest-com@forwardhub.com",
           "transferred": true,
           "transferredAt": "2021-03-05T10:11:16+00:00",
           "sent": true,
           "sentAt": "2021-03-05T10:11:19+00:00",
           "opened": false,
           "openedAt": null,
           "clicked": false,
           "clickedAt": null,
           "hardBounced": false,
           "hardBouncedAt": null,
           "softBounced": false,
           "softBouncedAt": null,
           "spam": false,
           "spamAt": null,
           "rejected": false,
           "rejectedAt": null,
           "unverified": false,
           "unverifiedAt": null,
           "hasBcc": 0,
           "isBcc": 0,
           "bccEmails": [],
           "bccOriginalEmail": null,
           "text": "x
Dear user@example.com!
Hi!
{PARAM1}
hu.webbandflow.co.uk
y",
           "html": "x
<br><br>
<img src="https://hu.webymon.com/images/secure-notsecure-w920-q75.jpg" />Dear user@example.com!
<br><br>
Hi!<br>
{PARAM1}
<br><br>
<a href="https://hu.webbandflow.co.uk/index.html">hu.webbandflow.co.uk</a>

<br><br>
y",
           "log": [
               {
                   "type": "send",
                   "date": "2021-03-05T10:11:19+00:00",
                   "message": null
               },
               {
                   "type": "transfer",
                   "date": "2021-03-05T10:11:16+00:00",
                   "message": null
               }
           ]
       }
   ],
   "targets": [
       "user@example.com"
   ],
   "cursor": "CmAKFAoHdHJhbnNhdBIJCICziMyJk+sCEkRqFGd+YXBpLWZvcndhcmRodWItY29tchILEgVFbWFpbBiAgIDYmr+ACgyiARdkZXZfdGVzdDFfX3duZnRlc3RfX2NvbRgAIAE=",
   "hasNext": false,
   "count": 1
}
  • items
    • a visszaadott email elemek listája
    • egy elem formátuma azonos az egy konkrét email-t visszadó API formátumával, így ott lesz részletesen kifejtve
  • targets
    • azoknak a címzetteknek a listája, amiket a rendszer lekért
    • azok is benne vannak ebben a listában, amiknél egyetlen levelet sem talált a rendszer, vagy a limit elérés miatt meg sem próbálta lekérni a leveleit
  • count
    • az items tömb mérete (nem az összes, a keresésnek megfelelő levél száma)
  • items
    • a visszaadott email elemek listája
    • egy elem formátuma azonos az egy konkrét email-t visszadó API formátumával, így ott lesz részletesen kifejtve
  • cursor
    • a következő lap lekéréséhez szükséges token, amit a start paraméterben kell küldeni
    • akkor is visszaad egy token-t az API, ha nincs több elem a listában
  • hasNext
    • true, amennyiben van rá esély, hogy még van elem a listában
    • amennyiben az utolsó oldalon pont annyi elem van, mint a pageSize paraméter, akkor is true, de valójában a következő lap már nem fog visszaadni elemeket
    • azaz akkor van vége a listának, ha
      • a hasNext false
      • vagy az items üres

Email lista méretének lekérése

Az email-ek listájának méretét a GET https://app.forwardhub.com/client/emails/count végponton lehet elérni. Ez a végpont az Email listázás API végpont kiegészítő funkciója.

A végpont paraméterezése azonos az Email listázás API paraméterezésével, ennek a végpontnak a feladata, hogy ugyanannak a listának a méretét adja vissza anélkül, hogy az email-ek részleteit feleslegesen lekérné.

Emellett meg lehet adni egy limit paramétert, amennyiben ezt a számot eléri a rendszer, nem folytatja tovább a számlálást, és a limit paraméter értékét adja vissza, mint count. Erre egy gyakorlati példa ha arra vagyunk kíváncsiak, hogy van-e legalább 100 darab X státuszú levél, de nem fontos, hogy pontosan mennyi, akkor le lehet kérni limit=100-al a számosságot, és ha az 100, akkor van legalább 100 darab.

Példa:

GET https://app.forwardhub.com/client/emails/count?target=user@example.com

vagy

GET https://app.forwardhub.com/client/emails/count?targets[]=user@example.com

vagy több címzettel

GET https://app.forwardhub.com/client/emails/count?targets[]=user@example.com&targets[]=user2@example.com

( indexelni is lehet a lista elemeket: GET https://app.forwardhub.com/client/emails/count?targets[0]=user@example.com&targets[1]=user2@example.com )

vagy egy string-ként küldve

GET https://app.forwardhub.com/client/emails/count?targetList=user@example.com,user2@example.com

{
   "count": 28,
   "targets": [
       "user@example.com"
   ]
}
  • count
    • a levelek listájának mérete
    • amennyiben a limit paraméter meg van adva, és attól több levelet találna a rendszer, a mező értéke azonos lesz a limit paraméterrel, és nem a valódi elem számot adja vissza
  • targets
    • azoknak a címzetteknek a listája, amiket a rendszer lekért
    • azok is benne vannak ebben a listában, amiknél egyetlen levelet sem talált a rendszer, vagy a limit elérés miatt meg sem próbálta lekérni a leveleit

Email lekérés

Amennyiben tudjuk egy levél azonosítóját (a fenti listából, vagy a levél küldő API hívás által visszaadott válasz-ból), le lehet kérni az összes adatát, illetve igény esetén, ha vannak csatolmányai, akkor azoknak a tartalmát is.

GET https://app.forwardhub.com/client/emails/EMAILID

ha a csatolmányok tartalmát is le akarjuk kérni, akkor https://app.forwardhub.com/client/emails/EMAILID?attachments=1

{
   "id": "6679963222671360",
   "target": "user@example.com",
   "type": "sys",
   "templateId": "5764518391054336",
   "emailListId": null,
   "emailListDay": null,
   "emailListTimed": null,
   "params": [],
   "priority": 1,
   "cause": "send via API",
   "batch": null,
   "realTarget": null,
   "debugLevel": 0,
   "subject": "teszt email",
   "createdAt": "2021-03-05T10:10:29+00:00",
   "attachments": [
       {
           "id": "0",
           "name": "file1.txt",
           "type": "text/plain",
           "size": "15",
           "content": "ZmlsZTEgY29udGVudA=="
       },
       {
           "id": "1",
           "name": "file2.txt",
           "type": "text/plain",
           "size": "15",
           "content": "ZmlsZTIgY29udGVudA=="
       },
       {
           "id": "2",
           "name": "ugyfeltajekoztato-210215.pdf",
           "type": "application/pdf",
           "size": "76617",
           "content": "JVBERi0xLjcNJeLjz9MNCjIxID...oxMTYNCiUlRU9GDQo="
       }
   ],
   "from": "test1-wnftest-com@forwardhub.com",
   "sender": "Test 1",
   "replyTo": "test1-wnftest-com@forwardhub.com",
   "transferred": true,
   "transferredAt": "2021-03-05T10:11:16+00:00",
   "sent": true,
   "sentAt": "2021-03-05T10:11:19+00:00",
   "opened": false,
   "openedAt": null,
   "clicked": false,
   "clickedAt": null,
   "hardBounced": false,
   "hardBouncedAt": null,
   "softBounced": false,
   "softBouncedAt": null,
   "spam": false,
   "spamAt": null,
   "rejected": false,
   "rejectedAt": null,
   "unverified": false,
   "unverifiedAt": null,
   "hasBcc": 0,
   "isBcc": 0,
   "bccEmails": [],
   "bccOriginalEmail": null,
   "text": "x
Dear user@example.com!
Hi!
{PARAM1}
hu.webbandflow.co.uk
y",
   "html": "x
<br><br>
<img src="https://hu.webymon.com/images/secure-notsecure-w920-q75.jpg" />Dear user@example.com!
<br><br>
Hi!<br>
{PARAM1}
<br><br>
<a href="https://hu.webbandflow.co.uk/index.html">hu.webbandflow.co.uk</a>

<br><br>
y",
   "log": [
       {
           "type": "send",
           "date": "2021-03-05T10:11:19+00:00",
           "message": null
       },
       {
           "type": "transfer",
           "date": "2021-03-05T10:11:16+00:00",
           "message": null
       }
   ]
}

Minden dátum mező W3C formátumban, UTC időzónában van visszaadva.

Amíg egy levél az outbox-ban van, addig a legtöbb mező értéke null vagy üres string, mivel ezeket a rendszer csak a küldéskor állítja be.

  • id
    • az email azonosítója
  • target
    • a levél címzettje
  • type
    • a levél template-jének típusa:
      • sys: rendszer levél
      • edm: EDM levél
  • templateId
    • a levél template-jének azonosítója
  • emailListId
    • ha egy email lista miatt lett kiküldve (EDM üzenetek), akkor annak az azonosítója
  • emailListDay
    • ha egy email lista email flow-ja miatt lett kiküldve, akkor az adott flow napja
  • emailListTimed
    • ha egy email lista időzített eleme miatt lett kiküldve, akkor az adott időzítés ideje
  • params
    • a levél paraméterei
      • System esetén az API híváskor küldött paraméterek, az alap paraméterek nélkül (template, target, attachments)
      • EDM esetén a rendszer által beállított paraméterek
  • priority
    • a levél kiküldésének prioritása
  • cause
    • a levél küldésének oka
    • System esetén általában “Send via API”
    • EDM esetén a konkrét ok szövegesen leírva
  • batch
    • EDM üzenetek esetén a tömeges email küldés azonosítója
  • realTarget
    • ha debug miatt végül nem az eredeti címzettnek kell kiküldve, akkor a tényleges címzett
  • debugLevel
    • a kiküldés pillanatában a levél template-jében beállított debug level
    • 0: normál küldés
    • 3: más címzettnek küldés (a realTarget-ben van, hogy kinek)
    • 6: visszautasítva (nem lesz kiküldve soha)
  • subject
    • a levél Subject mezeje
    • ha ez egy titkos másolat, akkor a mező értéke üres, és a bccOriginalEmail mezőben küldött értéket kell használni, mivel a két levél tartalma megegyezik
  • createdAt
    • a levél létrehozási ideje
    • System esetén az API hívás ideje
    • EDM esetén a cron futási ideje
  • attachments
    • a csatolmányok listája
    • egy elem struktúrája:
      • id
        • a csatolmány sorszáma
      • name
        • a csatolmány neve
      • type
        • a csatolmány mime type-ja
      • size
        • a csatolmány hozzávetőleges mérete
        • ez a base64 string hosszából van számítva, emiatt néhány byte eltérés lehet a számítás és a tényleges fájl méret között
      • content
        • csak akkor, ha a ?attachments=1 paraméterrel lett meghívva az API
        • az eredetileg beküldött base64 string
  • from
    • a levél From mezeje
  • sender
    • a levél küldőjének neve
  • replyTo
    • a levél Reply-To mezeje
  • transferred
    • true, ha ki lett küldve az SMTP szolgáltatónak
    • amíg nem true, addig az outbox-ban van a levél, és a legtöbb mező értéke üres
  • transferredAt
    • az SMTP szolgáltatónak küldés ideje
    • null, ha még nem lett elküldve
  • sent
    • true, ha az SMTP szolgáltató visszaigazolta a levél kiküldését
  • sentAt
    • a levél tényleges küldésének ideje
    • null, ha még nem lett elküldve
  • opened
    • true, ha a címzett megnyitotta a levelet
  • openedAt
    • a levél utolsó megnyitásának ideje
    • null, ha még nem lett megnyitva
  • clicked
    • true, ha a címzett lekattintotta a levelet
  • clickedAt
    • az utolsó kattintás ideje
    • null, ha még nem lett lekattintva
  • hardBounced
    • true, ha a levél hard bounce-olt
  • hardBouncedAt
    • az utolsó hard bounce ideje
    • null, ha még nem hard bounce-olt
  • softBounced
    • true, ha a levél soft bounce-olt
  • softBouncedAt
    • az utolsó soft bounce ideje
    • null, ha még nem soft bounce-olt
  • spam
    • true, ha a levél spam-nek lett jelölve
  • spamAt
    • az utolsó spam-nek jelölés ideje
    • null, ha még nem lett spam-nek jelölve
  • rejected
    • true, ha a levél küldése vissza lett utasítva
  • rejectedAt
    • a visszautasítás ideje
  • hasBcc
    • tartozik-e a levélhez titkos másolat
    • 0: nem
    • 1: igen
  • isBcc
    • a levél egy titkos másolata-e egy másik levélnek
    • 0: nem
    • 1: igen
  • bccEmails
    • a titkos másolatok hivatkozásának listája (ha tartozik a levélhez titkos másolat)
    • ez a lista csak onnantól tartalmaz hivatkozásokat, hogy a levél el lett küldve (azaz már nem az outbox-ban van), amíg az outbox-ban van, addig üres, de a hasBcc mező értéke már ekkor is lehet 1
    • egy elem struktúrája:
      • id: a másolat azonosítója
      • target: a másolat címzettje
  • bccOriginalEmail
    • az a levél, amihez ez a levél tartozik titkos másolatként
    • ha ez egy titkos másolat, akkor egy Email típusú strukúrát tartalmaz a mező
    • ha ez nem titkos másolat, akkor a mező értéke null, vagy egy üres tömb
  • text
    • a levél szövege txt formában (a html kódból van generálva)
    • ha ez egy titkos másolat, akkor a mező értéke üres, és a bccOriginalEmail mezőben küldött értéket kell használni, mivel a két levél tartalma megegyezik
  • html
    • a levél szövege (az eredeti, a template-ben megadott kód)
    • ha ez egy titkos másolat, akkor a mező értéke üres, és a bccOriginalEmail mezőben küldött értéket kell használni, mivel a két levél tartalma megegyezik
  • log
    • a levéllel kapcsolatos események listája
    • egy elem struktúrája:
      • type
        • az esemény típusa
        • lehetséges értékek:
          • transfer
          • send
          • hard_bounce
          • soft_bounce
          • open
          • click
          • spam
          • reject
      • date
        • az esemény dátuma
      • message
        • az eseményhez tartozó, opcionális üzenet

A következő mezőket, illetve a log mező bejegyzéseit az SMTP szolgáltató által küldött események állítják:

  • sent
  • opened
  • clicked
  • hardBounced
  • softBounced
  • spam
  • rejected

A rejected mezőt a rendszer is állíthatja, amennyiben a debugLevel = 6.

A send eseményt az SMTP szolgáltató közel realtime küldi, a többit kötegelve, általában 1-2 óránként. Mindegyik esetben az adott eseményhez tartozó dátum mező az esemény eredeti idejére van beállítva.