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=<kulcs>  
Ahol:         ^             ^          ^ API Kulcs  
              ^             Részegység  
              Szolgáltató címe.`  
  
  
### 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.  
  
#### 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=<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`


### 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!
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`