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.

207 lines
7.6 KiB

5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
2 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 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
5 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. (Opcionális) Feliratkozó nevének módosítása: `forcenamechange=<1|0>`
  28. #### Várható válaszok
  29. Sikeres feliratkozás: `success`, Sikertelen feliratkozás: `sub_error`,
  30. Nincs MX rekord: `no_mx_record` (ez lehet átmeneti hiba is),
  31. Rossz lista azonosító: `bad_list`, Sikertelen regisztráció: `reg_error`
  32. ### Feliratkozó eltávolítása listáról
  33. Feliratkozó eltávolításához szükségünk van a lista azonosítójára és a feliratkozó
  34. e-mail címére.
  35. A leiratkozást végző gyár: unsubscribe
  36. A kérés a következőképpen alakul:
  37. `POST: http://example.org/a/unsubscribe?key=<kulcs>`
  38. `DATA: list=<id>&email=<Feliratkozó E-mail>`
  39. #### Várható válaszok
  40. Sikeres leiratkozás: `success`, Sikertelen leiratkozás: `unsub_error`,
  41. Ismeretlen E-mail cím: `unknown_email`, Hiányzó paraméterek: `missing_parameters`
  42. ### Lista létrehozás
  43. Levelezőlista létrehozására alkalmas.
  44. A listát kezelő gyár: list
  45. A kérés a következőképpen alakul:
  46. `POST: http://example.org/a/list?key=<kulcs>`
  47. `DATA: new&name=<Lista neve>`
  48. #### Várható válaszok
  49. Sikeres kérés: `success`, Sikertelen kérés: `failed`,
  50. Nem megfelelő név: `bad_name`
  51. ### Lista törlése
  52. Levelezőlista törlésére alkalmas.
  53. A listát kezelő gyár: list
  54. A kérés a következőképpen alakul:
  55. `POST: http://example.org/a/list?key=<kulcs>`
  56. `DATA: remove&id=<Lista ID>`
  57. #### Várható válaszok
  58. Sikeres kérés: `success`, Sikertelen kérés: `failed`
  59. ### Listák lekérdezése
  60. Levelezőlisták lekérdezésére alkalmas.
  61. A listát kezelő gyár: list
  62. A kérés a következőképpen alakul:
  63. `POST: http://example.org/a/list?key=<kulcs>`
  64. `DATA: get`
  65. #### Várható válaszok
  66. Sikeres kérés: -tömb-
  67. ### Levél létrehozás
  68. Levelek létrehozására alkalmas.
  69. A leveleket kezelő gyár: newsletter
  70. A kérés a következőképpen alakul:
  71. `POST: http://example.org/a/newsletter?key=<kulcs>`
  72. `DATA: new&subject=<Levél tárgya>&message=<Levél HTML tartalma>&message_text=<Levél TEXT tartalma>`
  73. #### Várható válaszok
  74. Sikeres kérés: `success`, `id`, Sikertelen kérés: `failed`,
  75. Nem megfelelő tárgy: `bad_subject`, Túl hosszú üzenet: `message_too_powerful`,
  76. Túl rövid üzenet: `message_too_short`
  77. ### Levél küldése
  78. Levelek küldésére alkalmas.
  79. A leveleket kezelő gyár: newsletter
  80. A kérés a következőképpen alakul:
  81. `POST: http://example.org/a/newsletter?key=<kulcs>`
  82. `DATA: send&id=<Levél ID>&start=<Unix timestamp vagy 0 azonnal>`
  83. #### Várható válaszok
  84. Sikeres kérés: `success`, Már várólistán: `already_queued`, Sikertelen kérés: `failed`
  85. ### Levelek listázása
  86. Levelek listázására alkalmas.
  87. A leveleket kezelő gyár: newsletter
  88. A kérés a következőképpen alakul:
  89. `POST: http://example.org/a/newsletter?key=<kulcs>`
  90. `DATA: get`
  91. #### Várható válaszok
  92. Sikeres kérés: -tömb-
  93. ### Kampány létrehozása
  94. Kampányok létrehozására alkalmas.
  95. A leveleket kezelő gyár: campaign
  96. A kérés a következőképpen alakul:
  97. `POST: http://example.org/a/campaign?key=<kulcs>`
  98. `DATA: new&name=<Kampány neve>`
  99. #### Várható válaszok
  100. Sikeres kérés: `success`, `id`, Sikertelen kérés: `failed`
  101. ### Kampány törlése
  102. Kampányok törlésére alkalmas.
  103. A leveleket kezelő gyár: campaign
  104. A kérés a következőképpen alakul:
  105. `POST: http://example.org/a/campaign?key=<kulcs>`
  106. `DATA: remove&id=<Kampány ID>`
  107. #### Várható válaszok
  108. Sikeres kérés: `success`, Sikertelen kérés: `failed`
  109. ### Kampány frissítése (csatolás)
  110. Kampányok listához történő csatolására alkalmas.
  111. A leveleket kezelő gyár: campaign
  112. A kérés a következőképpen alakul:
  113. `POST: http://example.org/a/campaign?key=<kulcs>`
  114. `DATA: update&id=<Kampány ID>&lists=<Array of ListIDs>`
  115. #### Várható válaszok
  116. Sikeres kérés: `success`, Sikertelen kérés: `failed`
  117. ### Kampány csatolása levélhez
  118. Kampányok levélhez történő csatolására alkalmas.
  119. A leveleket kezelő gyár: campaign
  120. A kérés a következőképpen alakul:
  121. `POST: http://example.org/a/campaign?key=<kulcs>`
  122. `DATA: relations&campaign=<Kampány ID1,ID2,ID3>&newsletter=<Levél ID>`
  123. #### Várható válaszok
  124. Sikeres kérés: `success`, Sikertelen kérés: `failed`
  125. ### E-mail küldése
  126. Egyéni e-mail küldését, valamint annak sikerességének vizsgálatát teszi lehetővé.
  127. Az üzenet HTML és Plain text formában kerül kiküldésre. Ha a `message_text` értéke
  128. üres, a HTML formátumú levél tartalmával minusz HTML tag-ek lesz azonos. Az üzenet
  129. csak a HTML body részét tartalmazza! Nagy mennyiségű üzenet küldésére használja a
  130. newsletter, list és campaigns gyárakat!
  131. A küldést és ellenőrzést végző gyár: send
  132. A kérés a következőképpen alakul:
  133. `POST: http://example.org/a/send?key=<kulcs>`
  134. `DATA: to=<subscriber ID vagy Email cím>&subject=<Tárgy>&message=<Üzenet HTML formában>&message_text=<Üzenet TXT formában>`
  135. #### Várható válaszok
  136. Sikeres sorbaállítás: `message_queued`, `id`, Nem található feliratkozó: `subscriber_not_found`,
  137. Sikertelen fekiratkozó mentés: `subscriber_error`, Sikertelen sorbaállítás: `message_failed`,
  138. Csomagkorlát elérve: `quota_reached`, Hiányzó paraméter: `missing_parameter`
  139. ### E-mail küldés ellenőrzés
  140. A send gyáron keresztül küldött levelek ellenőrzésére alkalmas. A kimenő levelek
  141. pixel2 lekérésének idejét, a küldés befejezésének idejét és a sikerességét tudja.
  142. `GET: http://example.org/a/send?key=<kulcs>`
  143. `DATA: just_asking=<id>`
  144. #### Várható válaszok
  145. Sikeres lekérdezés: (status)`success/failed`, `read`, `to`, `time`
  146. Sikertelen lekérdezés: `wrong_id`
  147. ### Belépés távolról
  148. Lehetőség van távoli belépésre. Ilyenkor felhasználói név és jelszó megadása
  149. nélkül is lehetőség adódik az adminisztrációs felület elérésére. Az API kérés
  150. egy véletlenszerű kulcsot ad vissza, amit a http://example.org/ oldalnak kell
  151. elküldeni böngészőből.
  152. A belépést végző gyár: login
  153. A kérés a következőképpen alakul:
  154. `POST: http://example.org/a/login?key=<kulcs>`
  155. `DATA: rkey=<véletlenszerű string>`
  156. #### Várható válaszok
  157. Sikeres token generálás: `success` és `token`