11 KiB
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:
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ésre0— 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
$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
$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
$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());
}