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/<gyár>?key=
Ahol: example.org - szolgáltató, <gyár> - 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=<kulcs>
DATA: list=<id>&name=<Feliratkozó neve>&email=<Feliratkozó E-mail>&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. (Opcionális) Feliratkozó nevének módosítása: forcenamechange=<1|0>

Várható válaszok

Sikeres feliratkozás: success, Sikertelen feliratkozás: sub_error, Nincs MX rekord: no_mx_record (ez lehet átmeneti hiba is), 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=<kulcs>
DATA: list=<id>&email=<Feliratkozó E-mail>

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=<kulcs>
DATA: new&name=<Lista neve>

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=<kulcs>
DATA: remove&id=<Lista 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=<kulcs>
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=<kulcs>
DATA: new&subject=<Levél tárgya>&message=<Levél HTML tartalma>&message_text=<Levél TEXT tartalma>

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=<kulcs>
DATA: send&id=<Levél ID>&start=<Unix timestamp vagy 0 azonnal>

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=<kulcs>
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=<kulcs>
DATA: new&name=<Kampány neve>

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=<kulcs>
DATA: remove&id=<Kampány 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=<kulcs>
DATA: update&id=<Kampány ID>&lists=<Array of ListIDs>

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=<kulcs>
DATA: relations&campaign=<Kampány ID1,ID2,ID3>&newsletter=<Levél ID>

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=<kulcs>
DATA: to=<subscriber ID vagy Email cím>&subject=<Tárgy>&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=<kulcs>
DATA: just_asking=<id>

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=<kulcs>
DATA: rkey=<véletlenszerű string>

Várható válaszok

Sikeres token generálás: success és token