ninjaMail_public/README.md

# ninjaMail API

A ninjaMail levelező alkalmazásprogramozási interfészének (API) hivatalos dokumentációja és PHP klienskönyvtára.

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](#követelmények)
- [Bevezetés és hitelesítés](#bevezetés-és-hitelesítés)
- [API alap URL](#api-alap-url)
- [Hibakezelés](#hibakezelés)
- [API végpontok](#api-végpontok)
  - [Feliratkozó hozzáadása (subscribe)](#feliratkozó-hozzáadása)
  - [Feliratkozó eltávolítása (unsubscribe)](#feliratkozó-eltávolítása)
  - [Listák kezelése (list)](#listák-kezelése)
  - [Hírlevél létrehozása (newsletter)](#hírlevél-létrehozása)
  - [Hírlevél frissítése (newsletter)](#hírlevél-frissítése)
  - [Hírlevél küldése (newsletter)](#hírlevél-küldése)
  - [Hírlevelek listázása (newsletter)](#hírlevelek-listázása)
  - [Kampány létrehozása (campaign)](#kampány-létrehozása)
  - [Kampány törlése (campaign)](#kampány-törlése)
  - [Kampány frissítése – listák csatolása (campaign)](#kampány-frissítése-listák-csatolása)
  - [Kampány csatolása hírlevélhez (campaign)](#kampány-csatolása-hírlevélhez)
  - [Egyedi e-mail küldése (send)](#egyedi-e-mail-küldése)
  - [E-mail küldés állapotának ellenőrzése (send)](#e-mail-küldés-állapotának-ellenőrzése)
  - [Statisztikák lekérdezése (statistics)](#statisztikák-lekérdezése)
  - [Távoli belépés (login)](#távoli-belépés)
- [PHP kliens használati útmutató és példák](#php-kliens-használati-útmutató-és-példák)
  - [Inicializálás és távoli belépés](#inicializálás-és-távoli-belépés)
  - [Feliratkozás és leiratkozás](#feliratkozás-és-leiratkozás)
  - [Egyedi levél küldése](#egyedi-levél-küldése)
  - [Hírlevél létrehozása, frissítése és küldése](#hírlevél-létrehozása-frissítése-és-küldése)
  - [Kampány kezelése](#kampány-kezelése)
  - [Statisztika lekérdezése](#statisztika-lekérdezése)

---

## 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:

```php
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:

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

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

```php
$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

```php
$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

```php
$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

```php
$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

```php
$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

```php
$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();
}
```