208 lines
7.6 KiB
Markdown
208 lines
7.6 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`
|
|
|
|
|
|
### 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`
|