Add ng/README.md
This commit is contained in:
+429
@@ -0,0 +1,429 @@
|
|||||||
|
# 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/<gyár>?key=<kulcs>
|
||||||
|
```
|
||||||
|
|
||||||
|
| Elem | Leírás |
|
||||||
|
|-------------|-------------------------------------|
|
||||||
|
| `example.org` | A szolgáltató domainje |
|
||||||
|
| `<gyár>` | A funkciót kezelő végpont neve |
|
||||||
|
| `<kulcs>` | 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=<kulcs>
|
||||||
|
DATA: list=<id>&name=<Feliratkozó neve>&email=<E-mail>&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=<kulcs>
|
||||||
|
DATA: list=<id>&email=<E-mail>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 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=<kulcs>
|
||||||
|
DATA: new&name=<Lista neve>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 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=<kulcs>
|
||||||
|
DATA: remove&id=<Lista 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=<kulcs>
|
||||||
|
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=<kulcs>
|
||||||
|
DATA: new&subject=<Tárgy>&message=<HTML tartalom>&message_text=<Szöveges tartalom>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 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=<kulcs>
|
||||||
|
DATA: new&id=<Levél ID>&subject=<Tárgy>&message=<HTML tartalom>&message_text=<Szöveges tartalom>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 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=<kulcs>
|
||||||
|
DATA: send&id=<Levél ID>&start=<Unix timestamp vagy 0 azonnal>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 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=<kulcs>
|
||||||
|
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=<kulcs>
|
||||||
|
DATA: new&name=<Kampány neve>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 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=<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 (lista csatolás)
|
||||||
|
|
||||||
|
**Gyár:** `campaign`
|
||||||
|
|
||||||
|
```
|
||||||
|
POST: http://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 kérés |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Kampány csatolása levélhez
|
||||||
|
|
||||||
|
**Gyár:** `campaign`
|
||||||
|
|
||||||
|
```
|
||||||
|
POST: http://example.org/a/campaign?key=<kulcs>
|
||||||
|
DATA: relations&campaign=<Kampány ID1,ID2,ID3>&newsletter=<Levél ID>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 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 `<body>` tartalmát tartalmazza.
|
||||||
|
|
||||||
|
**Gyár:** `send`
|
||||||
|
|
||||||
|
```
|
||||||
|
POST: http://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` | 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=<kulcs>&just_asking=<id>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 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=<kulcs>
|
||||||
|
DATA: newsletter=<Levél ID>&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=<kulcs>
|
||||||
|
DATA: rkey=<véletlenszerű string>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 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('<p>Szia!</p>');
|
||||||
|
|
||||||
|
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('<h1>Hírek</h1><p>Tartalom...</p>');
|
||||||
|
|
||||||
|
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());
|
||||||
|
}
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user