Information about ninjaMail, API usage, examples, etc.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

205 lines
7.5 KiB

4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
1 year ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
3 years ago
3 years ago
3 years ago
3 years ago
2 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
  1. ninjaMail API
  2. ===============
  3. Ebben a fájlban olvashat arról, hogyan használhatja a levelező
  4. alkalmazásprogramozási interfészét.
  5. A példákban szereplő lekérések PHP programozási szemszögből készültek, viszont
  6. felhasználható más nyelven íródott projektekben is, amennyiben az rendelkezik
  7. CURL könyvtárral vagy más, GET és POST hívást támogató eszközzel.
  8. ## Bevezetés
  9. Az API használatához regisztráció után generálni kell egy kulcsot. Ez a
  10. Beállítások -> API menüből érhető el. A generált kulcsot tartsa titokban!
  11. Míg API kulccsal nem lehet bejelentkezni a webes felületen, az API felületen a
  12. legtöbb funkció elérhető. A kulcs felhasználásával lehetőség nyílik többek
  13. között feliratkozók hozzáadására, törlésére.
  14. ## API URL
  15. Az URL kulcsgenerálás után ugyan azon a felületen lesz látható.
  16. `Példa: http://example.org/a/<gyár>?key=<kulcs>
  17. Ahol: example.org - szolgáltató, <gyár> - részegység, <kulcs> - API kulcs
  18. ### Feliratkozó hozzáadása
  19. Feliratkozó hozzáadása esetén tudni kell a lista azonosítóját. Ez a webes
  20. felületre történő belépés után a Listák menüpontban a kettőskereszt oszlopban
  21. látható. A feliratkozást végző gyár: subscribe
  22. A kérés a következőképpen alakul:
  23. `POST: http://example.org/a/subscribe?key=<kulcs>`
  24. `DATA: list=<id>&name=<Feliratkozó neve>&email=<Feliratkozó E-mail>&activated=<1|0>`
  25. Az activated paraméter 1-es állásban megerősítettként rögzíti a feliratkozót,
  26. míg 0 állásban küld megerősítő hivatkozást a megadott címre.
  27. #### Várható válaszok
  28. Sikeres feliratkozás: `success`, Sikertelen feliratkozás: `sub_error`,
  29. Rossz lista azonosító: `bad_list`, Sikertelen regisztráció: `reg_error`
  30. ### Feliratkozó eltávolítása listáról
  31. Feliratkozó eltávolításához szükségünk van a lista azonosítójára és a feliratkozó
  32. e-mail címére.
  33. A leiratkozást végző gyár: unsubscribe
  34. A kérés a következőképpen alakul:
  35. `POST: http://example.org/a/unsubscribe?key=<kulcs>`
  36. `DATA: list=<id>&email=<Feliratkozó E-mail>`
  37. #### Várható válaszok
  38. Sikeres leiratkozás: `success`, Sikertelen leiratkozás: `unsub_error`,
  39. Ismeretlen E-mail cím: `unknown_email`, Hiányzó paraméterek: `missing_parameters`
  40. ### Lista létrehozás
  41. Levelezőlista létrehozására alkalmas.
  42. A listát kezelő gyár: list
  43. A kérés a következőképpen alakul:
  44. `POST: http://example.org/a/list?key=<kulcs>`
  45. `DATA: new&name=<Lista neve>`
  46. #### Várható válaszok
  47. Sikeres kérés: `success`, Sikertelen kérés: `failed`,
  48. Nem megfelelő név: `bad_name`
  49. ### Lista törlése
  50. Levelezőlista törlésére alkalmas.
  51. A listát kezelő gyár: list
  52. A kérés a következőképpen alakul:
  53. `POST: http://example.org/a/list?key=<kulcs>`
  54. `DATA: remove&id=<Lista ID>`
  55. #### Várható válaszok
  56. Sikeres kérés: `success`, Sikertelen kérés: `failed`
  57. ### Listák lekérdezése
  58. Levelezőlisták lekérdezésére alkalmas.
  59. A listát kezelő gyár: list
  60. A kérés a következőképpen alakul:
  61. `POST: http://example.org/a/list?key=<kulcs>`
  62. `DATA: get`
  63. #### Várható válaszok
  64. Sikeres kérés: -tömb-
  65. ### Levél létrehozás
  66. Levelek létrehozására alkalmas.
  67. A leveleket kezelő gyár: newsletter
  68. A kérés a következőképpen alakul:
  69. `POST: http://example.org/a/newsletter?key=<kulcs>`
  70. `DATA: new&subject=<Levél tárgya>&message=<Levél HTML tartalma>&message_text=<Levél TEXT tartalma>`
  71. #### Várható válaszok
  72. Sikeres kérés: `success`, `id`, Sikertelen kérés: `failed`,
  73. Nem megfelelő tárgy: `bad_subject`, Túl hosszú üzenet: `message_too_powerful`,
  74. Túl rövid üzenet: `message_too_short`
  75. ### Levél küldése
  76. Levelek küldésére alkalmas.
  77. A leveleket kezelő gyár: newsletter
  78. A kérés a következőképpen alakul:
  79. `POST: http://example.org/a/newsletter?key=<kulcs>`
  80. `DATA: send&id=<Levél ID>&start=<Unix timestamp vagy 0 azonnal>`
  81. #### Várható válaszok
  82. Sikeres kérés: `success`, Már várólistán: `already_queued`, Sikertelen kérés: `failed`
  83. ### Levelek listázása
  84. Levelek listázására alkalmas.
  85. A leveleket kezelő gyár: newsletter
  86. A kérés a következőképpen alakul:
  87. `POST: http://example.org/a/newsletter?key=<kulcs>`
  88. `DATA: get`
  89. #### Várható válaszok
  90. Sikeres kérés: -tömb-
  91. ### Kampány létrehozása
  92. Kampányok létrehozására alkalmas.
  93. A leveleket kezelő gyár: campaign
  94. A kérés a következőképpen alakul:
  95. `POST: http://example.org/a/campaign?key=<kulcs>`
  96. `DATA: new&name=<Kampány neve>`
  97. #### Várható válaszok
  98. Sikeres kérés: `success`, `id`, Sikertelen kérés: `failed`
  99. ### Kampány törlése
  100. Kampányok törlésére alkalmas.
  101. A leveleket kezelő gyár: campaign
  102. A kérés a következőképpen alakul:
  103. `POST: http://example.org/a/campaign?key=<kulcs>`
  104. `DATA: remove&id=<Kampány ID>`
  105. #### Várható válaszok
  106. Sikeres kérés: `success`, Sikertelen kérés: `failed`
  107. ### Kampány frissítése (csatolás)
  108. Kampányok listához történő csatolására alkalmas.
  109. A leveleket kezelő gyár: campaign
  110. A kérés a következőképpen alakul:
  111. `POST: http://example.org/a/campaign?key=<kulcs>`
  112. `DATA: update&id=<Kampány ID>&lists=<Array of ListIDs>`
  113. #### Várható válaszok
  114. Sikeres kérés: `success`, Sikertelen kérés: `failed`
  115. ### Kampány csatolása levélhez
  116. Kampányok levélhez történő csatolására alkalmas.
  117. A leveleket kezelő gyár: campaign
  118. A kérés a következőképpen alakul:
  119. `POST: http://example.org/a/campaign?key=<kulcs>`
  120. `DATA: relations&campaign=<Kampány ID1,ID2,ID3>&newsletter=<Levél ID>`
  121. #### Várható válaszok
  122. Sikeres kérés: `success`, Sikertelen kérés: `failed`
  123. ### E-mail küldése
  124. Egyéni e-mail küldését, valamint annak sikerességének vizsgálatát teszi lehetővé.
  125. Az üzenet HTML és Plain text formában kerül kiküldésre. Ha a `message_text` értéke
  126. üres, a HTML formátumú levél tartalmával minusz HTML tag-ek lesz azonos. Az üzenet
  127. csak a HTML body részét tartalmazza! Nagy mennyiségű üzenet küldésére használja a
  128. newsletter, list és campaigns gyárakat!
  129. A küldést és ellenőrzést végző gyár: send
  130. A kérés a következőképpen alakul:
  131. `POST: http://example.org/a/send?key=<kulcs>`
  132. `DATA: to=<subscriber ID vagy Email cím>&subject=<Tárgy>&message=<Üzenet HTML formában>&message_text=<Üzenet TXT formában>`
  133. #### Várható válaszok
  134. Sikeres sorbaállítás: `message_queued`, `id`, Nem található feliratkozó: `subscriber_not_found`,
  135. Sikertelen fekiratkozó mentés: `subscriber_error`, Sikertelen sorbaállítás: `message_failed`,
  136. Csomagkorlát elérve: `quota_reached`, Hiányzó paraméter: `missing_parameter`
  137. ### E-mail küldés ellenőrzés
  138. A send gyáron keresztül küldött levelek ellenőrzésére alkalmas. A kimenő levelek
  139. pixel2 lekérésének idejét, a küldés befejezésének idejét és a sikerességét tudja.
  140. `GET: http://example.org/a/send?key=<kulcs>`
  141. `DATA: just_asking=<id>`
  142. #### Várható válaszok
  143. Sikeres lekérdezés: (status)`success/failed`, `read`, `to`, `time`
  144. Sikertelen lekérdezés: `wrong_id`
  145. ### Belépés távolról
  146. Lehetőség van távoli belépésre. Ilyenkor felhasználói név és jelszó megadása
  147. nélkül is lehetőség adódik az adminisztrációs felület elérésére. Az API kérés
  148. egy véletlenszerű kulcsot ad vissza, amit a http://example.org/ oldalnak kell
  149. elküldeni böngészőből.
  150. A belépést végző gyár: login
  151. A kérés a következőképpen alakul:
  152. `POST: http://example.org/a/login?key=<kulcs>`
  153. `DATA: rkey=<véletlenszerű string>`
  154. #### Várható válaszok
  155. Sikeres token generálás: `success` és `token`