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`


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