# ninjaMail API Ebben a dokumentumban megismerheti a levelező alkalmazásprogramozási interfészének használatát. A példák PHP szemszögből készültek, de bármely nyelvből felhasználható, amely támogatja a cURL-t vagy GET/POST hívásokat. --- ## Bevezetés Az API használatához regisztráció után API kulcsot kell generálni a **Beállítások → API** menüpontban. A generált kulcsot tartsa titokban — a kulccsal a legtöbb funkció elérhető programozottan, beleértve feliratkozók hozzáadását és törlését is. Webes bejelentkezésre az API kulcs önmagában nem alkalmas. --- ## API URL A kulcsgenerálás után az API alap URL ugyanazon a felületen jelenik meg. ``` http://example.org/a/?key= ``` | Elem | Leírás | |-------------|-------------------------------------| | `example.org` | A szolgáltató domainje | | `` | A funkciót kezelő végpont neve | | `` | Az API hitelesítési kulcs | > **Megjegyzés:** Éles környezetben mindig HTTPS-t használjon. --- ## Hibakezelés A PHP kliens `RuntimeException`-t dob hálózati vagy JSON hibák esetén, `InvalidArgumentException`-t hiányzó vagy érvénytelen paraméterek esetén. Mindig try/catch blokkban hívja az API metódusokat: ```php try { $result = $mailer->send(); } catch (InvalidArgumentException $e) { // hiányzó / érvénytelen paraméter error_log($e->getMessage()); } catch (RuntimeException $e) { // hálózati hiba, JSON hiba, hiányzó kulcs error_log($e->getMessage()); } ``` --- ## Végpontok ### Feliratkozó hozzáadása **Gyár:** `subscribe` ``` POST: http://example.org/a/subscribe?key= DATA: list=&name=&email=&activated=<1|0> ``` Az `activated` paraméter: - `1` — a feliratkozó azonnal megerősítettként kerül rögzítésre - `0` — megerősítő e-mail kerül kiküldésre a megadott címre Opcionális: `forcenamechange=<1|0>` — meglévő feliratkozó nevének felülírása. #### Várható válaszok | Státusz | Leírás | |-------------------|--------------------------------| | `success` | Sikeres feliratkozás | | `sub_error` | Sikertelen feliratkozás | | `no_mx_record` | Nincs MX rekord (lehet átmeneti) | | `bad_list` | Érvénytelen lista azonosító | | `reg_error` | Sikertelen regisztráció | --- ### Feliratkozó eltávolítása **Gyár:** `unsubscribe` ``` POST: http://example.org/a/unsubscribe?key= DATA: list=&email= ``` #### Várható válaszok | Státusz | Leírás | |------------------------|---------------------------------| | `success` | Sikeres leiratkozás | | `unsub_error` | Sikertelen leiratkozás | | `unknown_email` | Ismeretlen e-mail cím | | `missing_parameters` | Hiányzó paraméterek | --- ### Lista létrehozása **Gyár:** `list` ``` POST: http://example.org/a/list?key= DATA: new&name= ``` #### Várható válaszok | Státusz | Leírás | |--------------|-----------------------| | `success` | Sikeres létrehozás | | `failed` | Sikertelen kérés | | `bad_name` | Nem megfelelő név | --- ### Lista törlése **Gyár:** `list` ``` POST: http://example.org/a/list?key= DATA: remove&id= ``` #### Várható válaszok | Státusz | Leírás | |-----------|--------------------| | `success` | Sikeres törlés | | `failed` | Sikertelen törlés | --- ### Listák lekérdezése **Gyár:** `list` ``` POST: http://example.org/a/list?key= DATA: get ``` #### Várható válasz Sikeres kérés esetén a listák tömbje. --- ### Levél létrehozása **Gyár:** `newsletter` ``` POST: http://example.org/a/newsletter?key= DATA: new&subject=&message=&message_text= ``` #### Várható válaszok | Státusz | Leírás | |------------------------|---------------------------| | `success` + `id` | Sikeres létrehozás | | `failed` | Sikertelen kérés | | `bad_subject` | Érvénytelen tárgy | | `message_too_powerful` | Túl hosszú üzenet | | `message_too_short` | Túl rövid üzenet | --- ### Levél frissítése **Gyár:** `newsletter` ``` POST: http://example.org/a/newsletter?key= DATA: new&id=&subject=&message=&message_text= ``` #### Várható válaszok Azonos a levél létrehozásával. --- ### Levél küldése **Gyár:** `newsletter` ``` POST: http://example.org/a/newsletter?key= DATA: send&id=&start= ``` #### Várható válaszok | Státusz | Leírás | |-------------------|--------------------------------| | `success` | Sikeres sorbaállítás | | `already_queued` | Már várólistán szerepel | | `failed` | Sikertelen kérés | --- ### Levelek listázása **Gyár:** `newsletter` ``` POST: http://example.org/a/newsletter?key= DATA: get ``` #### Várható válasz Sikeres kérés esetén a levelek tömbje. --- ### Kampány létrehozása **Gyár:** `campaign` ``` POST: http://example.org/a/campaign?key= DATA: new&name= ``` #### Várható válaszok | Státusz | Leírás | |------------------|----------------------| | `success` + `id` | Sikeres létrehozás | | `failed` | Sikertelen kérés | --- ### Kampány törlése **Gyár:** `campaign` ``` POST: http://example.org/a/campaign?key= DATA: remove&id= ``` #### Várható válaszok | Státusz | Leírás | |-----------|--------------------| | `success` | Sikeres törlés | | `failed` | Sikertelen törlés | --- ### Kampány frissítése (lista csatolás) **Gyár:** `campaign` ``` POST: http://example.org/a/campaign?key= DATA: update&id=&lists= ``` #### Várható válaszok | Státusz | Leírás | |-----------|---------------------| | `success` | Sikeres frissítés | | `failed` | Sikertelen kérés | --- ### Kampány csatolása levélhez **Gyár:** `campaign` ``` POST: http://example.org/a/campaign?key= DATA: relations&campaign=&newsletter= ``` #### Várható válaszok | Státusz | Leírás | |-----------|-------------------| | `success` | Sikeres csatolás | | `failed` | Sikertelen kérés | --- ### E-mail küldése Egyéni e-mail küldésére alkalmas. Nagy mennyiségű levélhez használja a `newsletter`, `list` és `campaign` gyárakat. Ha a `message_text` üres, az értéke a HTML tartalom tag-ek nélküli változata lesz. Az üzenet csak a HTML `` tartalmát tartalmazza. **Gyár:** `send` ``` POST: http://example.org/a/send?key= DATA: to=&subject=&message=&message_text= ``` #### Várható válaszok | Státusz | Leírás | |--------------------------|---------------------------------| | `message_queued` + `id` | Sikeres sorbaállítás | | `subscriber_not_found` | Ismeretlen feliratkozó | | `subscriber_error` | Feliratkozó mentési hiba | | `message_failed` | Sikertelen sorbaállítás | | `quota_reached` | Csomagkorlát elérve | | `missing_parameter` | Hiányzó paraméter | --- ### E-mail küldés ellenőrzése A `send` gyáron keresztül küldött levelek állapotát kérdezi le: az olvasás időpontját, a küldés befejezésének idejét és sikerességét. **Gyár:** `send` ``` GET: http://example.org/a/send?key=&just_asking= ``` #### Várható válaszok | Státusz | Mezők | Leírás | |-----------|------------------------------------|---------------------------| | `success` | `status`, `read`, `to`, `time` | Sikeres lekérdezés | | `failed` | `status`, `read`, `to`, `time` | Sikertelen küldés | | `wrong_id`| — | Érvénytelen azonosító | --- ### Statisztikák lekérdezése **Gyár:** `statistics` ``` POST: http://example.org/a/statistics?key= DATA: newsletter=&type=1 ``` #### Várható válasz A hírlevél statisztikai adatait tartalmazó objektum. --- ### Belépés távolról Lehetővé teszi az adminisztrációs felület elérését felhasználói név és jelszó megadása nélkül. Az API egy egyszer használatos tokent ad vissza, amelyet böngészőből kell elküldeni a `http://example.org/` oldalra. > **Biztonsági megjegyzés:** A PHP kliens `bin2hex(random_bytes(16))` segítségével generálja a véletlenszerű kulcsot — ne használjon gyengébb módszert (pl. `md5(time())`). **Gyár:** `login` ``` POST: http://example.org/a/login?key= DATA: rkey= ``` #### Várható válaszok | Státusz | Leírás | |---------------------|--------------------------------| | `success` + `token` | Sikeres token generálás | --- ## PHP használati példák ### Feliratkozó hozzáadása ```php $sub = new ninjaMailSubscription('https://example.org', 'az-api-kulcsom'); $sub->list(3); $sub->activated(true); try { $ok = $sub->subscribe('pelda@email.hu', 'Kovács János'); echo $ok ? 'Sikeres feliratkozás' : 'Sikertelen feliratkozás'; } catch (RuntimeException $e) { error_log($e->getMessage()); } ``` ### E-mail küldése ```php $mailer = new ninjaMailSend('https://example.org', 'az-api-kulcsom'); $mailer->to('pelda@email.hu'); $mailer->subject('Üdvözlünk!'); $mailer->message('

Szia!

'); try { $ok = $mailer->send(); echo $ok ? 'Levél elküldve' : 'Küldés sikertelen'; } catch (InvalidArgumentException $e) { echo 'Hiányzó mező: ' . $e->getMessage(); } catch (RuntimeException $e) { error_log($e->getMessage()); } ``` ### Hírlevél létrehozása és küldése ```php $nl = new ninjaMailNewsletter('https://example.org', 'az-api-kulcsom'); $nl->subject('Havi összefoglaló'); $nl->message('

Hírek

Tartalom...

'); try { $id = $nl->create(); if ($id) { $nl->send(); // azonnali küldés // $nl->send(strtotime('+1 day')); // ütemezett küldés } } catch (RuntimeException $e) { error_log($e->getMessage()); } ```