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.
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.
Az URL kulcsgenerálás után ugyan azon a felületen lesz látható.
`Példa: http://example.org/a/<gyár>?key=
Ahol: example.org - szolgáltató, <gyár> - részegység, - API kulcs
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>
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
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>
Sikeres leiratkozás: success
, Sikertelen leiratkozás: unsub_error
,
Ismeretlen E-mail cím: unknown_email
, Hiányzó paraméterek: missing_parameters
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>
Sikeres kérés: success
, Sikertelen kérés: failed
,
Nem megfelelő név: bad_name
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>
Sikeres kérés: success
, Sikertelen kérés: failed
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
Sikeres kérés: -tömb-
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>
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
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>
Sikeres kérés: success
, Már várólistán: already_queued
, Sikertelen kérés: failed
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
Sikeres kérés: -tömb-
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>
Sikeres kérés: success
, id
, Sikertelen kérés: failed
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>
Sikeres kérés: success
, Sikertelen kérés: failed
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>
Sikeres kérés: success
, Sikertelen kérés: failed
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>
Sikeres kérés: success
, Sikertelen kérés: failed
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>
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
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>
Sikeres lekérdezés: (status)success/failed
, read
, to
, time
Sikertelen lekérdezés: wrong_id
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>
Sikeres token generálás: success
és token