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