ninjaMail API =============== Ebben a fájlban olvashat arról, hogyan használhatja a levelező alkalmazásprogramozási interfészét. A példákban szereplő lekérések PHP programozási szemszögből készültek, viszont felhasználható más nyelven íródott projektekben is, amennyiben az rendelkezik CURL könyvtárral vagy más, GET és POST hívást támogató eszközzel. ## Bevezetés Az API használatához regisztráció után generálni kell egy kulcsot. Ez a Beállítások -> API menüből érhető el. A generált kulcsot tartsa titokban! Míg API kulccsal nem lehet bejelentkezni a webes felületen, az API felületen a legtöbb funkció elérhető. A kulcs felhasználásával lehetőség nyílik többek között feliratkozók hozzáadására, törlésére. ## API URL Az URL kulcsgenerálás után ugyan azon a felületen lesz látható. `Példa: http://example.org/a/?key= Ahol: example.org - szolgáltató, - részegység, - API kulcs ### Feliratkozó hozzáadása Feliratkozó hozzáadása esetén tudni kell a lista azonosítóját. Ez a webes felületre történő belépés után a Listák menüpontban a kettőskereszt oszlopban látható. A feliratkozást végző gyár: subscribe A kérés a következőképpen alakul: `POST: http://example.org/a/subscribe?key=` `DATA: list=&name=&email=&activated=<1|0>` Az activated paraméter 1-es állásban megerősítettként rögzíti a feliratkozót, míg 0 állásban küld megerősítő hivatkozást a megadott címre. #### Várható válaszok Sikeres feliratkozás: `success`, Sikertelen feliratkozás: `sub_error`, Rossz lista azonosító: `bad_list`, Sikertelen regisztráció: `reg_error` ### Feliratkozó eltávolítása listáról Feliratkozó eltávolításához szükségünk van a lista azonosítójára és a feliratkozó e-mail címére. A leiratkozást végző gyár: unsubscribe A kérés a következőképpen alakul: `POST: http://example.org/a/unsubscribe?key=` `DATA: list=&email=` #### Várható válaszok Sikeres leiratkozás: `success`, Sikertelen leiratkozás: `unsub_error`, Ismeretlen E-mail cím: `unknown_email`, Hiányzó paraméterek: `missing_parameters` ### Lista létrehozás Levelezőlista létrehozására alkalmas. A listát kezelő gyár: list A kérés a következőképpen alakul: `POST: http://example.org/a/list?key=` `DATA: new&name=` #### Várható válaszok Sikeres kérés: `success`, Sikertelen kérés: `failed`, Nem megfelelő név: `bad_name` ### Lista törlése Levelezőlista törlésére alkalmas. A listát kezelő gyár: list A kérés a következőképpen alakul: `POST: http://example.org/a/list?key=` `DATA: remove&id=` #### Várható válaszok Sikeres kérés: `success`, Sikertelen kérés: `failed` ### Listák lekérdezése Levelezőlisták lekérdezésére alkalmas. A listát kezelő gyár: list A kérés a következőképpen alakul: `POST: http://example.org/a/list?key=` `DATA: get` #### Várható válaszok Sikeres kérés: -tömb- ### Levél létrehozás Levelek létrehozására alkalmas. A leveleket kezelő gyár: newsletter A kérés a következőképpen alakul: `POST: http://example.org/a/newsletter?key=` `DATA: new&subject=&message=&message_text=` #### Várható válaszok Sikeres kérés: `success`, `id`, Sikertelen kérés: `failed`, Nem megfelelő tárgy: `bad_subject`, Túl hosszú üzenet: `message_too_powerful`, Túl rövid üzenet: `message_too_short` ### Levél küldése Levelek küldésére alkalmas. A leveleket kezelő gyár: newsletter A kérés a következőképpen alakul: `POST: http://example.org/a/newsletter?key=` `DATA: send&id=&start=` #### Várható válaszok Sikeres kérés: `success`, Már várólistán: `already_queued`, Sikertelen kérés: `failed` ### Levelek listázása Levelek listázására alkalmas. A leveleket kezelő gyár: newsletter A kérés a következőképpen alakul: `POST: http://example.org/a/newsletter?key=` `DATA: get` #### Várható válaszok Sikeres kérés: -tömb- ### Kampány létrehozása Kampányok létrehozására alkalmas. A leveleket kezelő gyár: campaign A kérés a következőképpen alakul: `POST: http://example.org/a/campaign?key=` `DATA: new&name=` #### Várható válaszok Sikeres kérés: `success`, `id`, Sikertelen kérés: `failed` ### Kampány törlése Kampányok törlésére alkalmas. A leveleket kezelő gyár: campaign A kérés a következőképpen alakul: `POST: http://example.org/a/campaign?key=` `DATA: remove&id=` #### Várható válaszok Sikeres kérés: `success`, Sikertelen kérés: `failed` ### Kampány frissítése (csatolás) Kampányok listához történő csatolására alkalmas. A leveleket kezelő gyár: campaign A kérés a következőképpen alakul: `POST: http://example.org/a/campaign?key=` `DATA: update&id=&lists=` #### Várható válaszok Sikeres kérés: `success`, Sikertelen kérés: `failed` ### Kampány csatolása levélhez Kampányok levélhez történő csatolására alkalmas. A leveleket kezelő gyár: campaign A kérés a következőképpen alakul: `POST: http://example.org/a/campaign?key=` `DATA: relations&campaign=&newsletter=` #### Várható válaszok Sikeres kérés: `success`, Sikertelen kérés: `failed` ### E-mail küldése Egyéni e-mail küldését, valamint annak sikerességének vizsgálatát teszi lehetővé. Az üzenet HTML és Plain text formában kerül kiküldésre. Ha a `message_text` értéke üres, a HTML formátumú levél tartalmával minusz HTML tag-ek lesz azonos. Az üzenet csak a HTML body részét tartalmazza! Nagy mennyiségű üzenet küldésére használja a newsletter, list és campaigns gyárakat! A küldést és ellenőrzést végző gyár: send A kérés a következőképpen alakul: `POST: http://example.org/a/send?key=` `DATA: to=&subject=&message=<Üzenet HTML formában>&message_text=<Üzenet TXT formában>` #### Várható válaszok Sikeres sorbaállítás: `message_queued`, `id`, Nem található feliratkozó: `subscriber_not_found`, Sikertelen fekiratkozó mentés: `subscriber_error`, Sikertelen sorbaállítás: `message_failed`, Csomagkorlát elérve: `quota_reached`, Hiányzó paraméter: `missing_parameter` ### E-mail küldés ellenőrzés A send gyáron keresztül küldött levelek ellenőrzésére alkalmas. A kimenő levelek pixel2 lekérésének idejét, a küldés befejezésének idejét és a sikerességét tudja. `GET: http://example.org/a/send?key=` `DATA: just_asking=` #### Várható válaszok Sikeres lekérdezés: (status)`success/failed`, `read`, `to`, `time` Sikertelen lekérdezés: `wrong_id` ### Belépés távolról Lehetőség van távoli belépésre. Ilyenkor felhasználói név és jelszó megadása nélkül is lehetőség adódik az adminisztrációs felület elérésére. Az API kérés egy véletlenszerű kulcsot ad vissza, amit a http://example.org/ oldalnak kell elküldeni böngészőből. A belépést végző gyár: login A kérés a következőképpen alakul: `POST: http://example.org/a/login?key=` `DATA: rkey=` #### Várható válaszok Sikeres token generálás: `success` és `token`