Az API URL hívásokkal működik, és a get paraméterekkel paraméterezhető. Az eredményt egyetlenegy stringben adja vissza, ami szintén URL kódolt változó és érték párokból áll. Ez a módszer rendkívül egyszerűen használható tetszőleges platformon és programozási környezetben.
Az egyik leggyakrabban elterjedt webes programozási nyelvhez, a php-hez példa programkódokat is mellékelünk. A php-s példakód alapján könnyen megírható más nyelven is a kód.
Az API nem teljeskörű, nem lehet tehát a ListaMester összes funkcióját elérni vele, hiszen erre rendszerint nincs is szükség. A jelenleg elérhető funkciók a csoporttagok manipulációjára szolgálnak (feliratkozás, leiratkozás, adatok listázása és módosítása). Az API nem támogatja a levélküldést és a különféle beállítások módosításait.
A ListaMesterben az adatok csoporthoz kötve vannak tárolva (a csoport a ListaMesterben lehet címlista vagy kérdőív). Minden csoportnak különféle adatmezői lehetnek, de két adatmező mindig kötelező: a név és az email cím. Az egyes adatmezőkre nem a nevük alapján hivatkozunk az API kérésekben, hanem minden mezőnek van egy egyszerű (számokat is tartalmazó) azonosítója (pl. "f734"). A név és email cím hivatkozási azonosítója mindig "name" és "email". A csoportok azonosítóit és mezők azonosítóit egy kérésben lekérhetjük az egész adatbázisra. Erre szolgál a "listFieldIDs" parancs.
Minden egyes URL híváshoz szükségesek az autentikációs adatok, azaz a felhasználói azonosító szám, és a jelszó kódolt alakja. Ezek az "uid" és "pwd" paraméterek. A művelet jogosultsága ezzel mindig ellenőrizve van. A paraméterek értékeit a listatulajdonos a "Beállítások -> Programozói interfész" menüpontban tudja megnézni. Ismeretük nem ad teljes hozzáférést a ListaMester fiókhoz a programozó számára, hiszen nem fog tudni velük belépni a webes felületen, ám az API által támogatott műveletekhez elegendő: látni fog minden információt, a címlistákat, stb.
További kötelező paraméter a "cmd", ami az aktuális parancs típusát adja meg, (pl. getMemberData a csoporttag adatainak lekérése). Az egyes parancsok paramétereket igényelnek (pl. a getMemberData számára szükséges a csoporttag "mid" azonosítója, amit a getAllMembers parancs hívásával előzőleg már lekérdeztünk). A paraméterek pontos leírását alább a Referencia szakaszban megadjuk.
A hívások visszatérési értéke mindig tartalmaz egy status nevű változót, aminek értéke helyes futás esetén "OK", hiba esetén "ERR", valamint egy msg nevű változót, ami egy angol nyelvű hibaüzenet a hiba okáról (vagy "Done" ha status="OK").
Az alábbi referencia szakaszban található példa URL-ek működnek, a böngészővel lehet azonnal próbálni a hívásokat egy teszt adatbázison. Értelemszerűen lehetnek hibaüzenetek is a hívások eredményeiben, attól függően, hogyan néz ki éppen a teszt adatbázis.
A paraméterek között nem tüntetjük fel a két kötelező paramétert (uid,pwd). A paraméterek értékeit UTF-8 kódolással kell megadni és URL kódolni.
Funkció: Áttekintő információ lekérése a teljes adatbázisról.
Ez a parancs a többitől eltérően nem a szokásos URL kódolt formában adja vissza az eredményt, hanem sima szövegként. Nem való ugyanis további gépi feldolgozásra, feladata csak annyi, hogy megadja a fejlesztő számára a csoportokhoz tartozó azonosítókat, a levelek és szűrők azonosítóit. Az eredmény közli az összes szükséges információt, azaz kilistázza az összes csoportot a rajtuk található feliratkozási adatmezők hivatkozásaival és neveivel,
Példa URL hívás:
https://listamester.hu/lmui/faces/api/Call.jsp?uid=984&pwd=39e0d4e70a123c9f001e13d6d7967142&cmd=listFieldIDs
Funkció: A csoport tagjainak listázása alapadatokkal (email, név, memberID)
Az eredmény formátuma egy (rendszerint hosszú) lista az alábbi változókkal:
Példa URL hívás:
https://listamester.hu/lmui/faces/api/Call.jsp?uid=984&pwd=39e0d4e70a123c9f001e13d6d7967142&cmd=getAllMembers&gid=1337
Funkció: A tag összes feliratkozási adatának lekérése
A csoporttag azonosítója rendszer szinten egyedi, tehát szükségtelen a csoport azonosítóját is megadni. Az eredmény formátuma lista az alábbi változókkal:
Példa URL hívás:
https://listamester.hu/lmui/faces/api/Call.jsp?uid=984&pwd=39e0d4e70a123c9f001e13d6d7967142&cmd=getMemberData&mid=629006
Funkció: A tag összes feliratkozási adatának lekérése. Eredménye ugyanaz, ami a getMemberData hívásnak.
Funkció: Az adott email című tagot keresi minden csoportban. Az eredmény mid, gid párokban jön.
Funkció: Új tag felvétele a csoportba.
Az fXX paramétereket nem kötelező megadni, de a name és email paraméterek mindig kötelezők. Ha egy több választ is megengedő kérdésmezőre több választ adunk, akkor azokat URL kódolás előtt sortörés karakterrel "\n" kell elválasztani. Ha returnMID=true meg van adva, akkor a válaszban visszaérkezik az új member ID is.
Funkció: Meglevő tag adatainak módosítása.
Működésében megegyezik a saveMemberrel. A tagot nem az egyedi mid-jével azonosítjuk, hanem az email címével (egy csoportban csak egyszer szerepelhet egy email cím). Ezért az email paraméter kötelező.
Funkció: Meglevő tag leiratkozása a csoportból.
A tagot az email címével azonosítjuk. Leiratkozás esetén az adatbázisban nyoma marad annak, hogy ő egyszer már listatag volt, Ez akkor praktikus, ha még egyszer tömeges címfelvételkor nem szeretnénk újra felvenni őt a listára.
Funkció: Meglevő tagok törlése a csoportból.
Törlés esetén az adatbázisban nem marad nyoma annak, hogy ő egyszer már listatag volt. Minden adat elveszik.
Funkció: Email küldése egy csoportnak.
A levél és az opcionálisan használt szűrő azonosítóját is a listFields funkcióval tudjuk lekérni. Figyelem: nagyobb levélkiküldési sebességek használata a fogadó szerverek kritikus befogadási szokásai (spam szűrők) miatt nem ajánlott. Az alapértelmezett értéknek max. néhányszorosát érdemes csak használni, még sürgős esetben is.
Példa URL hívás:
https://listamester.hu/lmui/faces/api/Call.jsp?uid=984&pwd=39e0d4e70a123c9f001e13d6d7967142&cmd=sendMailToGroup&gid=1337&eid=10197&fid=813
Funkció: Email küldése egy tagnak.
Az időzítés opcionális, ha nincs megadva, azonnal megy a levél.
Funkció: Levél megnyitási statisztikák lekérése.
A válasz egy hosszú szöveg, soronként egy megnyitási eseménnyel. Formátuma:
1. oszlop: email cím
2. oszlop: megnyitások száma
3. oszlop: dátum (szóközöket tartalmaz)
Funkció: Átkattintási statisztikák lekérése.
A válasz egy hosszú szöveg, soronként egy megnyitási eseménnyel. Formátuma:
1. oszlop: email cím
2. oszlop: megnyitások száma
3. oszlop: dátum (szóközöket tartalmaz)
Funkció: Új csoport létrehozása egy létező csoport másolásával. A csoport adatmezői másolódnak, a tagjai nem.
Az eredmény formátuma:
Példa URL hívás:
https://listamester.hu/lmui/faces/api/Call.jsp?uid=984&pwd=39e0d4e70a123c9f001e13d6d7967142&cmd=createGroup&gid=1337&name=ujCsoportTeszt
Funkció: CSV adatok lekérése a csoportból. Az adatok a http get kérésre válaszul azonnal jönnek, tehát itt nem a szokásos formátumban jön a válasz, hanem a kérésre válaszként egyből jön az eredmény. A CSV fájl utf8 kódolású, vessző a szeparátor (,), és idézőjelben (") vannak az adatok. A csoportban levő összes adatmező értéke exportálásra kerül.
Funkció: Új adatok bevitele csoportba. Az email mező kötelező, a név opcionális, de ha nincs megadva, akkor az email kukac előtti része lesz. Az összes többi (egyedi) adat opcionális. Ha az adott email cím már létezik a csoportban, akkor az itt megadott adatmezőket felülírjuk az új értékkel, de más adatokat nem törlünk.
Funkció: Törli az összes csoporttagot, azok minden adatával. A törlölt tagokról nem készül másolat, teljesen elvesznek az adatok.
Funkció: Számla készítése a tag számára.
Az invoiceId paraméter értéke a számla szerkesztésénél leolvasható (API ID). Az amount opcionális paraméter értéke az első számla tétel bruttó egységárát írja felül, ha meg van adva.