A dokumentáció ismerteti a közvetlen HTTP (cURL, GET/POST) végpontok hívását, valamint a modern, szigorúan típusos PHP 8.1+ kliensosztályok használatát.

Tartalomjegyzék

Követelmények
Bevezetés és hitelesítés
API alap URL
Hibakezelés
API végpontok
PHP kliens használati útmutató és példák

Követelmények

A PHP kliens használatához az alábbi környezet szükséges:

PHP 8.1 vagy újabb (declare(strict_types=1);, típusos osztálymezők és metódusok)
curl PHP kiterjesztés
json PHP kiterjesztés

Bevezetés és hitelesíté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 kezelje bizalmasan — a kulccsal a funkciók túlnyomó része elérhető programozottan, beleértve a feliratkozók kezelését, kampányok indítását és egyedi levelek küldését.

Webes adminisztrációs belépésre az API kulcs önmagában nem alkalmas (erre a távoli login végpont által adott egyszer használatos token szolgál).

API alap URL

A kulcsgenerálás után az API URL a felületen is megjelenik:

https://example.org/a/<végpont>/?key=<kulcs>

Elem	Leírás
`example.org`	A szolgáltató domain címe / alap URL-je
`<végpont>`	A meghívandó funkciót kezelő végpont neve (pl. `subscribe`, `send`, `newsletter`)
`<kulcs>`	Az API hitelesítési kulcs

Biztonsági megjegyzés: Éles környezetben mindig biztonságos HTTPS kapcsolatot használjon!

Hibakezelés

A modern PHP kliens kétféle kivételt dobhat:

InvalidArgumentException: ha egy kötelező mező hiányzik vagy érvénytelen (pl. hiányzó lista ID feliratkozáskor, üres címzett/tárgy/üzenet küldéskor, üres kampánynév).
RuntimeException: kommunikációs vagy hitelesítési hibák esetén (hiányzó gazdagép vagy API kulcs, cURL hálózati hiba, érvénytelen JSON válasz).

A legutóbbi sikeres API kérés nyers, dekódolt JSON válasza elérhető az objektum publikus $data mezőjében ($client->data).

Ajánlott try/catch mintázat:

try {
    $mailer = new ninjaMailSend('https://example.org', 'API_KEY');
    $mailer->to('ugyfel@example.com');
    $mailer->subject('Értesítés');
    $mailer->message('<p>Üdvözöljük!</p>');
    $ok = $mailer->send();
} catch (InvalidArgumentException $e) {
    // Kliensoldali validációs hiba
    error_log('Validációs hiba: ' . $e->getMessage());
} catch (RuntimeException $e) {
    // Hálózati vagy szerveroldali JSON hiba
    error_log('API hiba: ' . $e->getMessage());
}

API végpontok

Feliratkozó hozzáadása

Új feliratkozót ad hozzá a megadott azonosítójú listához. A lista azonosítója a webes adminisztrációs felületen a Listák menüpontban, a kettőskereszt (#) oszlopban található.

Végpont: subscribe

POST: https://example.org/a/subscribe/?key=<kulcs>
DATA: list=<id>&name=<Feliratkozó neve>&email=<E-mail>&activated=<1|0>&forcenamechange=<1|0>

Paraméterek:

list (kötelező): A levelezőlista azonosítója (pozitív egész szám).
email (kötelező): A feliratkozó e-mail címe.
name (opcionális): A feliratkozó neve.
activated (kötelező):
- 1: a feliratkozó azonnal megerősítettként (aktívként) kerül mentésre.
- 0: a rendszer megerősítő e-mailt küld a megadott címre.
forcenamechange (opcionális):
- 1: ha az e-mail cím már szerepel a listában, a feliratkozó neve felülírásra kerül.
- 0: meglévő feliratkozó esetén a név változatlan marad.

Várható válaszok

Státusz	Leírás
`success`	Sikeres feliratkozás
`sub_error`	Sikertelen feliratkozás
`no_mx_record`	Nincs érvényes MX rekord (lehet átmeneti DNS hiba is)
`bad_list`	Érvénytelen lista azonosító
`reg_error`	Sikertelen regisztráció

Feliratkozó eltávolítása

Feliratkozó törlése az adott listáról.

Végpont: unsubscribe

POST: https://example.org/a/unsubscribe/?key=<kulcs>
DATA: list=<id>&email=<E-mail>

Paraméterek:

list (kötelező): A levelezőlista azonosítója.
email (kötelező): A leiratkozó e-mail címe.

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 a megadott listában
`missing_parameters`	Hiányzó kötelező paraméterek

Listák kezelése

Levelezőlisták létrehozása, törlése és listázása a nyers API végponton keresztül.

Megjegyzés: A PHP klienskönyvtár a lista-műveletekhez nem tartalmaz külön burkolóosztályt; a hívások közvetlenül a ninjaMail::process('list', $data) metódussal kezdeményezhetők, míg a ninjaMailSubscription::list(int $id) metódus a fel- és leiratkozás cél-listájának kiválasztására szolgál.

Végpont: list

Lista létrehozása

POST: https://example.org/a/list/?key=<kulcs>
DATA: new&name=<Lista neve>

Státusz	Leírás
`success`	Sikeres létrehozás
`failed`	Sikertelen kérés
`bad_name`	Nem megfelelő vagy üres név

Lista törlése

POST: https://example.org/a/list/?key=<kulcs>
DATA: remove&id=<Lista ID>

Státusz	Leírás
`success`	Sikeres törlés
`failed`	Sikertelen törlés

Listák lekérdezése

POST: https://example.org/a/list/?key=<kulcs>
DATA: get

Válasz: Sikeres kérés esetén a listák tömbje/objektuma.

Hírlevél létrehozása

Új hírlevél piszkozatot hoz létre a megadott tartalommal.

Végpont: newsletter

POST: https://example.org/a/newsletter/?key=<kulcs>
DATA: new&subject=<Tárgy>&message=<HTML tartalom>&message_text=<Szöveges tartalom>

Paraméterek:

new: Műveletjelző.
subject: A hírlevél tárgya.
message: A levél HTML tartalma.
message_text (opcionális): A levél egyszerű szöveges (Plain text) változata. Ha nincs megadva, automatikusan a HTML tartalomból származik a HTML tag-ek eltávolításával.

Várható válaszok

Státusz	Leírás
`success` + `id`	Sikeres létrehozás, visszaadja az új hírlevél azonosítóját
`failed`	Sikertelen kérés
`bad_subject`	Érvénytelen vagy üres tárgy
`message_too_powerful`	Túl hosszú levéltartalom
`message_too_short`	Túl rövid levéltartalom

Hírlevél frissítése

Meglévő hírlevél tartalmának és tárgyának módosítása.

Végpont: newsletter

POST: https://example.org/a/newsletter/?key=<kulcs>
DATA: new&id=<Levél ID>&subject=<Tárgy>&message=<HTML tartalom>&message_text=<Szöveges tartalom>

Várható válaszok: megegyeznek a hírlevél létrehozásánál leírtakkal.

Hírlevél küldése

Hírlevél azonnali vagy ütemezett kiküldése.

Végpont: newsletter

POST: https://example.org/a/newsletter/?key=<kulcs>
DATA: send&id=<Levél ID>&start=<Unix timestamp vagy 0>

Paraméterek:

send: Műveletjelző.
id: A kiküldendő hírlevél azonosítója.
start: Unix időbélyeg az ütemezéshez, vagy 0 / üres érték azonnali kiküldéshez.

Várható válaszok

Státusz	Leírás
`success`	Sikeresen sorba állítva kiküldésre
`already_queued`	A levél már szerepel a kiküldési várólistán
`failed`	Sikertelen sorbaállítás

Hírlevelek listázása

Lekérdezi az elérhető hírlevelek listáját.

Végpont: newsletter

POST: https://example.org/a/newsletter/?key=<kulcs>
DATA: get

Válasz: Sikeres kérés esetén a leveleket tartalmazó lista / objektum.

Kampány létrehozása

Új kampányt hoz létre.

Végpont: campaign

POST: https://example.org/a/campaign/?key=<kulcs>
DATA: new&name=<Kampány neve>

Várható válaszok

Státusz	Leírás
`success` + `id`	Sikeres létrehozás, visszaadja az új kampány azonosítóját
`failed`	Sikertelen létrehozás

Kampány törlése

Törli a kiválasztott kampányt.

Végpont: campaign

POST: https://example.org/a/campaign/?key=<kulcs>
DATA: remove&id=<Kampány 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 – listák csatolása

Levelezőlistákat rendel egy meglévő kampányhoz.

Végpont: campaign

POST: https://example.org/a/campaign/?key=<kulcs>
DATA: update&id=<Kampány ID>&lists=<Lista ID-k tömbje>

Várható válaszok

Státusz	Leírás
`success`	Sikeres frissítés
`failed`	Sikertelen frissítés

Kampány csatolása hírlevélhez

Hírlevelet rendel a kampányhoz.

Végpont: campaign

POST: https://example.org/a/campaign/?key=<kulcs>
DATA: relations&id=<Kampány ID>&newsletter=<Levél ID>

Megjegyzés: A PHP kliens az attach() metódusban az id mezőben küldi el az aktív kampány azonosítóját. Közvetlen HTTP kérések esetén több kampány azonosítója vesszővel elválasztva a campaign=<ID1,ID2...> mezőben is átadható.

Várható válaszok

Státusz	Leírás
`success`	Sikeres hozzárendelés
`failed`	Sikertelen művelet

Egyedi e-mail küldése

Egyéni, tranzakciós e-mail kiküldésére alkalmas.
Nagy mennyiségű, tömeges levélküldéshez a newsletter, list és campaign végpontokat használja!

Az üzenet csak a HTML <body> belső tartalmát tartalmazza. Ha a message_text nincs megadva, automatikusan a HTML tag-ek nélküli szövegből generálódik.

Végpont: send

POST: https://example.org/a/send/?key=<kulcs>
DATA: to=<Feliratkozó ID vagy E-mail>&subject=<Tárgy>&message=<HTML tartalom>&message_text=<Szöveges tartalom>

Várható válaszok

Státusz	Leírás
`message_queued` + `id`	Sikeresen sorba állítva a kiküldéshez
`subscriber_not_found`	A megadott feliratkozó nem található
`subscriber_error`	Feliratkozó mentési hiba
`message_failed`	Sikertelen sorbaállítás
`quota_reached`	Elérte a csomagban engedélyezett korlátot
`missing_parameter`	Hiányzó kötelező mező

E-mail küldés állapotának ellenőrzése

A send végponton keresztül küldött egyedi levelek kézbesítési és megnyitási állapotának ellenőrzésére szolgál.

Végpont: send

GET: https://example.org/a/send/?key=<kulcs>&just_asking=<id>

Paraméter:

just_asking: A kiküldött levél azonosítója (id), amit a sikeres küldéskor adott vissza az API.

Várható válaszok

Státusz	Visszaadott mezők	Leírás
`success`	`status`, `read`, `to`, `time`	Sikeres lekérdezés; a levél sikeresen elküldve (és megnyitva, ha `read` be van állítva)
`failed`	`status`, `read`, `to`, `time`	Sikertelen küldés
`wrong_id`	—	Nem létező levél azonosító

Statisztikák lekérdezése

Kiküldött hírlevelek részletes statisztikai mutatóinak (megnyitások, kattintások, visszapattanók stb.) lekérdezése.

Végpont: statistics

POST: https://example.org/a/statistics/?key=<kulcs>
DATA: newsletter=<Levél ID>&type=1

Válasz: A statisztikai adatokat tartalmazó objektum.

Távoli belépés

Lehetővé teszi az adminisztrációs felület közvetlen elérését felhasználónév és jelszó megadása nélkül.
Az API kérés egy egyszer használatos bejelentkezési tokent generál, amellyel a böngészőből átirányítható a felhasználó.

Végpont: login

POST: https://example.org/a/login/?key=<kulcs>
DATA: rkey=<véletlenszerű string>

Biztonsági megjegyzés: A PHP kliens kriptográfiailag biztonságos bin2hex(random_bytes(16)) segítségével generálja az rkey paramétert. Ne használjon gyenge megoldásokat (pl. md5(time())).

Várható válaszok

Státusz	Leírás
`success` + `token`	Sikeres token generálás. A belépési link a megadott oldalra vezet a token átadásával.

PHP kliens használati útmutató és példák

A PHP kliens használatához illessze be a ninjamail.class.php fájlt:

require_once __DIR__ . '/ninjamail.class.php';

Inicializálás és távoli belépés

$api = new ninjaMail('https://example.org', 'AZ_ON_API_KULCSA');

if (!$api->check()) {
    die('Hiányzó gazdagép vagy API kulcs!');
}

// Egyszer használatos bejelentkezési token kérése
try {
    $loginData = $api->login();
    if (($loginData->status ?? '') === 'success') {
        echo 'Bejelentkezési token: ' . $loginData->token;
    }
} catch (RuntimeException $e) {
    error_log('Hiba a távoli belépéskor: ' . $e->getMessage());
}

Feliratkozás és leiratkozás

$sub = new ninjaMailSubscription('https://example.org', 'AZ_ON_API_KULCSA');

// Lista kiválasztása
$sub->list(12);

// true = azonnali aktiválás; false = megerősítő levél küldése
$sub->activated(true);

// Opcionális: meglévő feliratkozó nevének felülírása engedélyezett
$sub->namechange(true);

try {
    // Feliratkozás
    $success = $sub->subscribe('teszt@example.com', 'Teszt Elek');
    if ($success) {
        echo 'Sikeres feliratkozás!';
    } else {
        echo 'Sikertelen feliratkozás. Válasz: ' . json_encode($sub->data);
    }

    // Leiratkozás ugyanarról a listáról
    $unsubSuccess = $sub->unsubscribe('teszt@example.com');
    if ($unsubSuccess) {
        echo 'Sikeres leiratkozás!';
    }
} catch (InvalidArgumentException $e) {
    echo 'Paraméterhiba: ' . $e->getMessage();
} catch (RuntimeException $e) {
    echo 'API kommunikációs hiba: ' . $e->getMessage();
}

Egyedi levél küldése

$mailer = new ninjaMailSend('https://example.org', 'AZ_ON_API_KULCSA');
$mailer->to('ugyfel@example.com');
$mailer->subject('Rendelés visszaigazolása');
$mailer->message(
    '<h1>Köszönjük a vásárlást!</h1><p>A rendelését feldolgozzuk.</p>',
    'Köszönjük a vásárlást! A rendelését feldolgozzuk.' // opcionális plain text
);

try {
    $sent = $mailer->send();
    if ($sent) {
        echo 'Levél sikeresen sorba állítva!';
    } else {
        echo 'Küldési hiba: ' . json_encode($mailer->data);
    }
} catch (InvalidArgumentException $e) {
    echo 'Hiányzó kötelező adat: ' . $e->getMessage();
} catch (RuntimeException $e) {
    echo 'Hálózati hiba: ' . $e->getMessage();
}

Hírlevél létrehozása, frissítése és küldése

$nl = new ninjaMailNewsletter('https://example.org', 'AZ_ON_API_KULCSA');
$nl->subject('Havi hírlevelünk - 2026 Október');
$nl->message('<p>Itt olvashatóak az e havi újdonságok...</p>');

try {
    // 1. Hírlevél létrehozása
    $newsletterId = $nl->create();

    if ($newsletterId !== false) {
        echo 'Hírlevél létrehozva, ID: ' . $newsletterId . PHP_EOL;

        // 2. Hírlevél frissítése szükség esetén
        $nl->subject('Havi hírlevelünk - 2026 Október (Frissített tárgy)');
        $nl->update();

        // 3. Azonnali kiküldés:
        $queued = $nl->send();

        // Vagy ütemezett kiküldés holnap reggel 8-kor:
        // $queued = $nl->send(strtotime('+1 day 08:00'));

        if ($queued) {
            echo 'Hírlevél sikeresen sorba állítva a kiküldéshez!';
        }
    }

    // 4. Elérhető hírlevelek listázása
    $allNewsletters = $nl->get();
} catch (InvalidArgumentException $e) {
    echo 'Paraméterhiba: ' . $e->getMessage();
} catch (RuntimeException $e) {
    echo 'Hiba a hírlevél művelet során: ' . $e->getMessage();
}

Kampány kezelése

$campaign = new ninjaMailCampaign('https://example.org', 'AZ_ON_API_KULCSA');

try {
    // 1. Új kampány létrehozása
    $campaignId = $campaign->create('Tavaszi Akció 2026');

    if ($campaignId !== false) {
        echo 'Kampány létrehozva, ID: ' . $campaignId . PHP_EOL;

        // 2. Levelezőlisták hozzárendelése (lista azonosítók tömbje)
        $campaign->update([12, 15]);

        // 3. Hírlevél csatolása a kampányhoz
        $campaign->attach(42);

        // 4. Kampány törlése szükség esetén
        // $campaign->remove();
    }
} catch (InvalidArgumentException $e) {
    echo 'Paraméterhiba: ' . $e->getMessage();
} catch (RuntimeException $e) {
    echo 'Kampány hiba: ' . $e->getMessage();
}

Statisztika lekérdezése

$stats = new ninjaMailStatistics('https://example.org', 'AZ_ON_API_KULCSA');

try {
    $newsletterId = 42;
    $result = $stats->get($newsletterId);
    print_r($result);
} catch (InvalidArgumentException $e) {
    echo 'Érvénytelen hírlevél ID: ' . $e->getMessage();
} catch (RuntimeException $e) {
    echo 'Statisztika lekérdezési hiba: ' . $e->getMessage();
}

README.md Unescape Escape

ninjaMail API

Tartalomjegyzék

Követelmények

Bevezetés és hitelesítés

API alap URL

Hibakezelés

API végpontok

Feliratkozó hozzáadása

Várható válaszok

Feliratkozó eltávolítása

Várható válaszok

Listák kezelése

Lista létrehozása

Lista törlése

Listák lekérdezése

Hírlevél létrehozása

Várható válaszok

Hírlevél frissítése

Hírlevél küldése

Várható válaszok

Hírlevelek listázása

Kampány létrehozása

Várható válaszok

Kampány törlése

Várható válaszok

Kampány frissítése – listák csatolása

Várható válaszok

Kampány csatolása hírlevélhez

Várható válaszok

Egyedi e-mail küldése

Várható válaszok

E-mail küldés állapotának ellenőrzése

Várható válaszok

Statisztikák lekérdezése

Távoli belépés

Várható válaszok

PHP kliens használati útmutató és példák

Inicializálás és távoli belépés

Feliratkozás és leiratkozás

Egyedi levél küldése

Hírlevél létrehozása, frissítése és küldése

Kampány kezelése

Statisztika lekérdezése

README.md