ninjaMail_public/README.md

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: example.org - szolgáltató, <gyár> - részegység, <kulcs> - 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`