7.6 KiB
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