Release 0.9a: Move ng to main, modernize PHP 8.1+ client, update documentation and add Gitea workflow
This commit is contained in:
sandros committed
1 parent
76e09c0b96
commit
67bc8aa462
9 files changed
+1560
-1455
No files matched your search
@@ -1,207 +1,643 @@
|
||||
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: example.org - szolgáltató, <gyár> - részegység, <kulcs> - API kulcs
|
||||
|
||||
|
||||
# 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
|
||||
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.
|
||||
(Opcionális) Feliratkozó nevének módosítása: `forcenamechange=<1|0>`
|
||||
|
||||
#### Várható válaszok
|
||||
Sikeres feliratkozás: `success`, Sikertelen feliratkozás: `sub_error`,
|
||||
Nincs MX rekord: `no_mx_record` (ez lehet átmeneti hiba is),
|
||||
Rossz lista azonosító: `bad_list`, Sikertelen regisztráció: `reg_error`
|
||||
|
||||
Ú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ó.
|
||||
|
||||
### 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é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
|
||||
Sikeres leiratkozás: `success`, Sikertelen leiratkozás: `unsub_error`,
|
||||
Ismeretlen E-mail cím: `unknown_email`, Hiányzó paraméterek: `missing_parameters`
|
||||
|
||||
| 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ó |
|
||||
|
||||
### 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>`
|
||||
---
|
||||
|
||||
### 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
|
||||
Sikeres kérés: `success`, Sikertelen kérés: `failed`,
|
||||
Nem megfelelő név: `bad_name`
|
||||
|
||||
| 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 |
|
||||
|
||||
### 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>`
|
||||
---
|
||||
|
||||
### 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
|
||||
Sikeres kérés: `success`, Sikertelen kérés: `failed`
|
||||
|
||||
| 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 |
|
||||
|
||||
### 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`
|
||||
---
|
||||
|
||||
### 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
|
||||
Sikeres kérés: -tömb-
|
||||
|
||||
| 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 |
|
||||
|
||||
### 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`
|
||||
### Hírlevelek listázása
|
||||
|
||||
Lekérdezi az elérhető hírlevelek listáját.
|
||||
|
||||
### 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égpont:** `newsletter`
|
||||
|
||||
#### Várható válaszok
|
||||
Sikeres kérés: `success`, Már várólistán: `already_queued`, Sikertelen kérés: `failed`
|
||||
```
|
||||
POST: https://example.org/a/newsletter/?key=<kulcs>
|
||||
DATA: get
|
||||
```
|
||||
|
||||
Válasz: Sikeres kérés esetén a leveleket tartalmazó lista / objektum.
|
||||
|
||||
### 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>`
|
||||
|
||||
Ú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
|
||||
Sikeres kérés: `success`, `id`, Sikertelen kérés: `failed`
|
||||
|
||||
| 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
|
||||
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>`
|
||||
|
||||
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
|
||||
Sikeres kérés: `success`, Sikertelen kérés: `failed`
|
||||
|
||||
| Státusz | Leírás |
|
||||
|---|---|
|
||||
| `success` | Sikeres törlés |
|
||||
| `failed` | Sikertelen törlés |
|
||||
|
||||
### 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>`
|
||||
---
|
||||
|
||||
### 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
|
||||
Sikeres kérés: `success`, Sikertelen kérés: `failed`
|
||||
|
||||
| Státusz | Leírás |
|
||||
|---|---|
|
||||
| `success` | Sikeres frissítés |
|
||||
| `failed` | Sikertelen frissítés |
|
||||
|
||||
### 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>`
|
||||
---
|
||||
|
||||
### 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
|
||||
Sikeres kérés: `success`, Sikertelen kérés: `failed`
|
||||
|
||||
| Státusz | Leírás |
|
||||
|---|---|
|
||||
| `success` | Sikeres hozzárendelés |
|
||||
| `failed` | Sikertelen művelet |
|
||||
|
||||
### 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>`
|
||||
---
|
||||
|
||||
### 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
|
||||
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`
|
||||
|
||||
| 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 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>`
|
||||
---
|
||||
|
||||
### 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
|
||||
Sikeres lekérdezés: (status)`success/failed`, `read`, `to`, `time`
|
||||
Sikertelen lekérdezés: `wrong_id`
|
||||
|
||||
| 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ó |
|
||||
|
||||
### 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>`
|
||||
---
|
||||
|
||||
### 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
|
||||
Sikeres token generálás: `success` és `token`
|
||||
|
||||
| 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();
|
||||
}
|
||||
```
|
||||
Reference in new issue
Block a user