94 lines
4.2 KiB
Markdown
94 lines
4.2 KiB
Markdown
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`
|