A bejegyzés tartalma:
- Feliratkozó hozzáadása
- Feliratkozó módosítása
- Feliratkozók kötegelt módosítása
- Adatmódosító űrlap linkje
- Landing oldal linkje
- Feliratkozók adatainak lekérdezése
- Szegmens(ek) feliratkozóinak lekérdezése
- Adatok lekérdezése XML formátumban
- Feliratkozó leiratkoztatása
- Feliratkozó törlése
- Lista feliratkozóinak száma
- Szegmensben lévő feliratkozók száma
- Levélküldés
Feliratkozó hozzáadása
Hozzáad egy új feliratkozót az e-mail listához. Az API híváshoz szükséges egy a listához feliratkozó űrlap. A listában szereplő bármely mező kaphat értéket az API hívásban. Ha a feliratkozó e-mail címe már szerepel a listában és az e-mail cím egyedi azonosító, akkor a feliratkozó hozzáadása nem fog megtörténni.
Ha a listához tartozik egy aktív feliratkozáskori időzítéssel ellátott e-mail, akkor az a feliratkozáskor kiküldésre kerül a hozzáadott felhasználónak. Ha az API hívásban használt űrlap kettős opt-in típusú, akkor a megerősítés kérő levél kerül elküldésre, természetesen csak akkor ha az időzítése létezik és aktív.
FONTOS: Az API híváshoz használt űrlapon ne legyen bekapcsolva a Robotfeliratkozások kiszűrése Google reCAPTCHA használatával funkció.
Erőforrás:
https://api.salesautopilot.com/subscribe/<nl_id>/form/<ns_id>
Paraméterek:
E-mail lista azonosítója amelyhez a feliratkozót hozzá szeretné adni.
Az e-mail listához tartozó feliratkozó űrlap azonosítója.
A hívás törzsének (body) tartalmaznia kell az e-mail lista mezőit és a mezőhöz tartozó értékeket JSON formátumban. Ha az e-mail cím egyedi azonosító az e-mail listában, akkor a törzsnek tartalmaznia kell az e-mail cím mezőt és értékét. Az IP címet a mssys_ipaddress
mezőben lehet átadni.
Törzs:
{"email" : "test@mailmasterplus.hu",
"mssys_firstname" : "Elek",
"mssys_lastname" : "Teszt",
"mssys_company" : "XYZ Kft."}
Válasz
A hozzáadott feliratkozó azonosítóját tartalmazza.
Válasz sikeres hívás esetén:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
3
Válasz hiba esetén:
Hibakód: 403
Érték:
-1: ha az email cím egyedi azonosító az email listában és az email cím már szerepel a listában.
-2: email cím szintaktikai hiba.
-3: az űrlapnál be van kapcsolva a Google Recaptcha és ezért nem sikerült a feliratkozás.
0: ismeretlen hiba.
Feliratkozó módosítása
Az adott e-mail listában szereplő feliratkozók bármely adatát módosítja. Azon mezők amelyek nem szerepelnek az API hívás törzsében nem kerülnek módosításra. Szükség van egy az e-mail listához tartozó adatmódosító űrlapra.
A módosítandó feliratkozót kétféle módon tudja beazonosítani az API hívásban: a feliratkozó azonosítója (ID) alapján vagy bármely a listában szereplő mező értéke alapján. Az utóbbi esetben minden olyan feliratkozó adata módosításra kerül aki megfelel a megadott feltételnek, vagyis a megadott mező értéke egyenlő az API hívásban átadott értékkel.
Lehetőség van több feliratkozó adatainak kötegelt módosítására. Ebben az esetben a hívás törzsében kell megadni a módosítandó rekord azonosítására szolgáló paramétereket (id_field,id_value).
Adatmódosítás azonosító alapján:
https://api.salesautopilot.com/update/<nl_id>/form/<ns_id>/record/<id>
Paraméterek:
Annak az email listának az azonosítója, amelyben a módosítandó feliratkozó szerepel.
Adatmódosító űrlap azonosítója
A módosítandó feliratkozó azonosítója
Adatmódosítás egy adott mező értéke alapján:
https://api.salesautopilot.com/update/<nl_id>/form/<ns_id>/field/<field_name>/value/<field_value>
Paraméterek:
Annak az email listának az azonosítója, amelyben a módosítandó feliratkozók szerepelnek.
Adatmódosító űrlap azonosítója
A mező neve amely értéke meghatározza a módosítandó feliratkozókat.
A mező értéke amely alapján meghatározásra kerülnek a módosítandó feliratkozók
Az API hívás törzse tartalmazza a módosítandó mezőket és az új értékeket JSON formátumban.
Törzs:
{"email" : "info@mailmasterplus.hu",
"mssys_company" : "Cégem Kft."}
Több feliratkozó adatainak egyidejű (kötegelt) módosítása:
https://api.salesautopilot.com/update/<nl_id>/form/<ns_id>
Paraméterek:
Annak az email listának az azonosítója, amelyben a módosítandó feliratkozók szerepelnek.
Adatmódosító űrlap azonosítója
Az API hívás törzsében, altömbökként kell megadni a módosítandó feliratkozók paramétereit. A módosítandó paramétereket tartalmazó altömb data altömbjében kell megadni a módosítandó mező-érték párokat. Az id_field kulccsal kell megadni, hogy mely paraméter alapján kívánja beazonosítani a módosítandó rekordot, az id_value paraméterben kell megadni a hozzá tartozó értéket. Például az id_field = 'email', id_value='info@emesz.hu' az info@emesz.hu email című feliratkozót módosítja.
Törzs:
[{"data":{"mssys_company" : "Cégem Kft."},
"id_field" : "email",
"id_value" : "info@mailmasterplus.hu",
},{"data":{"mssys_company" : "Másik cégem Kft."},
"id_field" : "email",
"id_value" : "info@skycentrum.hu",
}]
FIGYELEM: API-n keresztül történő adatmódosításokról alapértelmezetten nem érkezik értesítés, tehát nem lépnek életbe a listánál megadott értesítés beállítások. Emögött a működés mögött az az indok húzódik meg, hogy az API-ból történő frissítés sok esetben sokkal gyakrabban történik, mintha a feliratkozó egy űrlapon keresztül frissítene. Mivel ez akár napi több ezer update hívást is jelenthet, ezekről az eseményekről csak akkor küld a rendszer értesítést a cél lista beállításai alapján, ha ezt a felhasználó kifejezetten kéri.
Az update metódus esetében a cél listán beállított értesítéseket azzal aktiválhatja, ha az URL végén elhelyezi a /sendnotice karaktersort.
Feliratkozó módosítása értesítéssel:
https://api.salesautopilot.com/update/<nl_id>/form/<ns_id>/record/<id>/sendnotice
Válasz
Tartalmazza a módosított feliratkozók számát.
Sikeres hívás válasza:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
1
Hiba esetén a válasz törzse üres lesz.
Feliratkozók kötegelt módosítása
Egy hívással tudja módosítani tetszőleges feliratkozók bármely adatát. A feliratkozónként egy-egy altömbben kell átadni a módosítandó adatokat. Feliratkozónként akár más-más adatokat is lehet módosítani. Ha a módosítandó adatok között szerepel az id kulcs, akkor az adott azonosítójú feliratkozó kerül módosításra, de lehetőség van bármely mező értéke alapján is módosítani. Ez utóbbi esetben a mssys_idparam altömb field és value kulcsaiban kell megadni, hogy melyik mező, melyik értékű előforduláshoz tartozó rekordjainál történjen a módosítás. FONTOS: ha nem id
alapján történik a frissítés, akkor előfordulhat, hogy egynél több rekord is módosításra kerül.
FIGYELEM: a kötegelt módosítás nagy mennyiségű feliratkozó gyors módosítására szolgál, az adatmódosítás során nem történik mezőszinkron, nem hajtódnak végre műveletek, sem időzítések. Tehát csak abban az esetben használja a kötegelt módosítást, ha az előbbiekre nincs szüksége.
https://api.salesautopilot.com/batchupdate/<listID>
Paraméterek:
Az e-mail lista azonosítója amelyhez az űrlap tartozik.
Törzs `id` alapján történő azonosítással:
[{"id" : "123",
"mezo1" : "Új érték",
"mezo2" : "Másik érték"},
{"id" : "129",
"mezo1" : "Érték",
"mezo2" : "Újabb érték"}]
Törzs tetszőleges mező alapján történő azonosítással:
[{"mssys_idparam" : {"email":"valaki@gmail.com"},
"mezo1" : "Új érték",
"mezo2" : "Másik érték"},
{"mssys_idparam" : {"email":"masikemail@gmail.com"},
"mezo1" : "Érték",
"mezo2" : "Újabb érték"}]
Válasz
Módosított feliratkozók száma.
Adatmódosító űrlap linkje
Visszaadja az adott feliratkozóra vonatkozó adatmódosító űrlap linkjét.
Adatmódosító űrlap linkje:
https://api.salesautopilot.com/updateformlink/<nl_id>/<ns_id>/<id>/secure
Paraméterek:
Az e-mail lista azonosítója amelyhez az űrlap tartozik.
Az űrlap azonosítója, amely linkje megjelenítésre kerül.
Feliratkozó azonosítója az email listában, akinek az adatait az űrlap behelyettesíti és módosítja.
Opcionális paraméter. Ha átadásra kerül, akkor az adatmódosító űrlapra mutató link https protokollal kerül visszaadásra.
Válasz
Adott feliratkozóra vonatkozó adatmódosító űrlap linkje.
Landing oldal linkje
Visszaadja a landing oldal adott feliratkozóhoz tartozó linkjét.
Landing oldal linkje:
https://api.salesautopilot.com/landingpagelink/<nl_id>/<lp_id>/<id>
Paraméterek:
Az e-mail lista azonosítója amelyhez a landing oldal tartozik.
A landing oldal azonosítója.
Feliratkozó azonosítója az email listában, akinek az adatait a landing oldal behelyettesíti.
Válasz
A landing oldal adott feliratkozóhoz tartozó linkje.
Feliratkozók adatainak lekérdezése
Visszaadja a feltételnek megfelelő feliratkozók adatait, az összes mezővel ami a listában szerepel. Az alábbi módokon történhet a lekérdezés.
Összes feliratkozó lekérdezése a listából:
https://api.salesautopilot.com/list/<nl_id>
Paraméterek:
Az e-mail lista azonosítója amelyből le szeretnénk kérdezni.
Egy adott feliratkozó lekérése azonosító alapján:
https://api.salesautopilot.com/list/<nl_id>/record/<id>
Paraméterek:
Az e-mail lista azonosítója amelyből le szeretnénk kérdezni.
A feliratkozó azonosítója amely adatait lekérdezzük.
Feliratkozók lekérése adott mező értéke alapján:
https://api.salesautopilot.com/list/<nl_id>/field/<field_name>/value/<field_value>
Paraméterek:
Az e-mail lista azonosítója amelyből le szeretnénk kérdezni.
Mező neve amely értéke alapján le szeretnénk kérdezni a feliratkozókat.
Mező értéke amely alapján le szeretnénk kérdezni a feliratkozókat. Az értékben használhatók * (joker) karakterek, pl. *kutya* kifejezéssel a mező értékében bárhol előforduló "kutya" szóra találatot ad.
Feliratkozók lekérése megadott mezők értéke alapján:
https://api.salesautopilot.com/list/<nl_id>
https://api.salesautopilot.com/list/<nl_id>/order/<orderfield>/<order_dir>/<limit>
Paraméterek:
Az e-mail lista azonosítója amelyből le szeretnénk kérdezni.
Opcionális paraméterek:
Milyen mező alapján legyen sorbarendezve az eredmény. A mező nevét kell megadni.
A sorrend iránya. asc: növekvő sorrend, desc: csökkenő sorrend.
Kilistázandó rekordok száma. Ha pl. csak az időrendben utolsó feliratkozót szeretné listázni, akkor az orderfield értéke legyen subdate, az orderdir értéke desc, a limit értéke pedig 1.
A hívás törzsében tudja átadni a mező-érték párokat amelyek alapján szűkíteni szeretné a lekérdezést illetve ha a lista csak bizonyos mezőinek értékeit szeretné visszakapni, akkor a törzsben tudja felsorolni a mezőneveket. Az egyes mező-érték párok ÉS logikai operátorral kerülnek összekapcsolásra, azaz mindegyik mező-érték pár szűkíti a lekérdezés feltételét. A hívás törzse az alábbi felépítésű:
Hívás törzse:
{"mezo1" : "érték1",
"mezo2" : "érték2"}
Ha még kifinomultabb feltételeket szeretne összeállítani, akkor az értékpárok helyett a mezőt, az operátort és az értéket kell egy-egy altömbben definiálni. Például ha 2015. januári feliratkozókat szeretné listázni, akkor a hívás törzse ebben az esetben az alábbi felépítésű legyen:
Hívás törzse:
[{"field" : "subdate",
"operator" : ">=",
"value" : "2015-01-01 00:00:00"},
{"field" : "subdate",
"operator" : "<=",
"value" : "2015-01-31 23:59:59"}]
A listázandó mezőket listFields
kulccsal tudja megadni. Ha feltételeket is megad a törzsben, akkor a listázandó mezőket a feltételek utána adja meg:
Hívás törzse:
[{"field" : "subdate",
"operator" : ">=",
"value" : "2015-01-01 00:00:00"},
{"field" : "subdate",
"operator" : "<=",
"value" : "2015-01-31 23:59:59"},
{"listFields":["email","subdate"]}]
Válasz
Tartalmazza a feliratkozók adatait JSON formátumban.
Sikeres hívás válasza:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[{"id" : "1"
"subdate" : "2012-03-12 09:30:23",
"active" : "1",
"mssys_last_activity_date" : "2012-03-29 11:11:22",
"email" : "test@mailmasterplus.hu",
"mssys_firstname" : "Teszt",
"mssys_lastname" : "Telek",
"mssys_company" : "XYZ Kft."},
{"id" : "5"
"subdate" : "2012-03-12 10:01:20",
"active" : "1",
"mssys_last_activity_date" : "2012-03-29 11:12:01",
"email" : "info@mailmasterplus.hu",
"mssys_firstname" : "Béla",
"mssys_lastname" : "Kis",
"mssys_company" : "Test Bt."}]
Megrendelés lista esetén a products
altömbben fognak szerepelni a rendelt termékek adatai. Ha nincs a feltételnek megfelelő feliratkozó a válasz törzse üres.
Szegmens(ek) feliratkozóinak lekérdezése
Visszaadja a megadott szegmens(ek)ben lévő feliratkozók adatait, az összes mezővel ami a listában szerepel.
Lekérdezés feliratkozás sorrendjében illetve adott mező alapján sorrendezve:
https://api.salesautopilot.com/filteredlist/<nl_id>
https://api.salesautopilot.com/filteredlist/<nl_id>/order/<orderfield>/<order_dir>/<limit>
Paraméterek:
Az e-mail lista azonosítója amelyből le szeretnénk kérdezni.
Opcionális paraméterek:
Milyen mező alapján legyen sorbarendezve az eredmény. A mező nevét kell megadni.
A sorrend iránya. asc: növekvő sorrend, desc: csökkenő sorrend.
Kilistázandó rekordok száma. Ha pl. csak az időrendben utolsó feliratkozót szeretné listázni, akkor az orderfield értéke legyen subdate, az orderdir értéke desc, a limit értéke pedig 1.
A hívás törzsében át kell adni a szegmensek azonosítóit. Ha több szegmenst ad át, akkor azok uniójából történik a lekérdezés.
Hívás törzse:
[12134,12355]

Válasz
Tartalmazza a feliratkozók adatait JSON formátumban.
Sikeres hívás válasza:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[{"id" : "1"
"subdate" : "2012-03-12 09:30:23",
"active" : "1",
"mssys_last_activity_date" : "2012-03-29 11:11:22",
"email" : "test@mailmasterplus.hu",
"mssys_firstname" : "Teszt",
"mssys_lastname" : "Telek",
"mssys_company" : "XYZ Kft."},
{"id" : "5"
"subdate" : "2012-03-12 10:01:20",
"active" : "1",
"mssys_last_activity_date" : "2012-03-29 11:12:01",
"email" : "info@mailmasterplus.hu",
"mssys_firstname" : "Béla",
"mssys_lastname" : "Kis",
"mssys_company" : "Test Bt."}]
Ha nincs a feltételnek megfelelő feliratkozó a válasz törzse üres.
Adatok lekérdezése XML formátumban
A list metódus helyett a list.xml metódust használva az adatok XML formátumban kerülnek elküldésre.
Erőforrás:
https://api.salesautopilot.com/list.xml/<nl_id>/record/<id>
Sikeres hívás válasza:
<subscribers>
<subdata>
<subdata>
<id>1</id>
<subdate>2016-08-04 09:55:11</subdate>
<active>1</active>
<email>teszt@elek.com</email>
<mssys_lastname>Teszt<mssys_lastname>
<mssys_firstname>Elek</mssys_firstname>
... Ebben a részben a feliratkozóhoz tartozó összes többi mező is megjelenik
<products>
<product>
<oi_id>93</oi_id>
<oi_sku>T1</oi_sku>
<oi_name>1000 forintos teszt termék</oi_name>
<oi_price>787.40</oi_price>
<oi_quantity>1</oi_quantity>
<oi_netto_sum>787.40</oi_netto_sum>
<oi_vat_percent>27</oi_vat_percent>
<oi_brutto_sum>1000.00</oi_brutto_sum>
<oi_currency>HUF</oi_currency>
<prod_id>123456</prod_id>
</product>
... Ebben a részben az összes többi rendelt termék is megjelenik, amennyiben megrendelés listáról van szó, és a rendelés nem üres.
</products>
</subdata>
.... Ebben a részben az összes többi lekért feliratkozó is megjelenik
</subscribers>
Feliratkozó leiratkoztatása
Adott e-mail listán, egy aktív feliratkozó státuszát leiratkozottra állítja, a feliratkozónak a rendszer ezután nem küld email-t.
A feliratkozót e-mail cím vagy azonosító alapján tudja leiratkoztatni.
Kérés:
https://api.salesautopilot.com/unsubscribe/<nl_id>/record/<id>
Paraméterek:
E-mail lista azonosítója amelyről a feliratkozót le szeretné iratkoztatni.
A feliratkozó azonosítója akit le szeretne iratkoztatni.
Kérés:
https://api.salesautopilot.com/unsubscribe/<nl_id>/email/<email>
Paraméterek:
E-mail lista azonosítója amelyről a feliratkozót le szeretné iratkoztatni.
A feliratkozó e-mail címe akit le szeretne iratkoztatni.
Kérés:
https://api.salesautopilot.com/unsubscribe/<nl_id>/field/<field_name>/value/<value>
Paraméterek:
E-mail lista azonosítója amelyről a feliratkozót le szeretné iratkoztatni.
Mező neve ami alapján beazonosítja a feliratkozót.
Mező értéke ami alapján beazonosítja a feliratkozót.
Válasz
Válasz sikeres hívás esetén:
HTTP/1.1 200 OK
1
Válasz hiba esetén:
A válasz -1 lesz, ha valamilyen hiba miatt - pl. az azonosító vagy e-mail cím nem szerepel a listán vagy már leiratkozott - nem sikerül a leiratkoztatást.
HTTP/1.1 200 OK
-1
Feliratkozó törlése
Véglegesen töröl egy feliratkozót az e-mail listából.
Kérés:
https://api.salesautopilot.com/delete/<nl_id>/record/<id>
Paraméterek:
E-mail lista azonosítója amelyből a feliratkozók törölni szerentné.
A feliratkozó azonosítója akit törölni szeretne.
Válasz
Válasz sikeres hívás esetén:
HTTP/1.1 200 OK
1
Válasz hiba esetén:
A válasz -1 lesz, ha valamilyen hiba miatt - pl. az azonosító vagy e-mail cím nem szerepel a listán vagy már leiratkozott - nem sikerül a törlés.
HTTP/1.1 200 OK
-1
Lista feliratkozóinak száma
Visszaadja egy adott lista feliratkozóinak számát. A számban benne vannak a leiratkozott és hibás email cím miatt inaktívak is.
Kérés:
https://api.salesautopilot.com/listtotalcount/<nl_id>
Paraméterek:
A lista azonosítója. A "Feliratkozók" fülön a lista neve mellett találja kiírva # jel után.
Válasz
Válasz sikeres hívás esetén, a listában lévő feliratkozók száma. Például:
HTTP/1.1 200 OK
3130
Válasz hiba esetén:
A megfelelő HTTP hibakód.
Szegmensben lévő feliratkozók száma
Visszaadja egy adott szegmensben lévő feliratkozók számát.
Kérés:
https://api.salesautopilot.com/getsegmentnum/<nls_id>
Paraméterek:
Szegmens azonosítója. A szegmensek listázása oldalon a szegmens szerkesztés ikon címkéjénél jelenik meg.
Válasz
Válasz sikeres hívás esetén, a szegmensben lévő feliratkozók száma. Például:
HTTP/1.1 200 OK
14
Válasz hiba esetén:
A megfelelő HTTP hibakód.
Levélküldés
Az API-n keresztül lehetőség van egy meglévő, időzítéssel rendelkező levél tetszőleges időpontban, egy adott feliratkozónak történő kiküldésére. A levél az API hívást követően néhány percen belül kiküldésre kerül. A MailMaster-ben létre kell hoznia a levelet és az időzítést (bármilyen típusút). A kiküldött levélben működnek a tartalom személyre szabás mezőkódok és feltételes tartalmak is.
Kérés:
https://api.salesautopilot.com/sendmail
A kérés törzse tartalmazza a kiküldendő levelek paramétereit. Minden egyes levél egy altömbben kell, hogy szerepeljen.
Kérés törzse:
[{"send_id" : "11111",
"contactid" : 121,
"mssys_text_content_part" : "Ide írja a szöveges részben megjelenítendő szöveget.",
"mssys_html_content_part" : "Ide írja a HTML részben megjelenítendő szöveget."},
{"send_id" : "11111",
"contactid" : 122
"mssys_text_content_part" : "Ide írja a szöveges részben megjelenítendő szöveget.",
"mssys_html_content_part" : "Ide írja a HTML részben megjelenítendő szöveget."}]
Kötelező paraméterek:
Az időzítés azonosítója. Az időzítés neve után zárójelben a # után szerepel 5 vagy 6 jegyű szám.
A feliratkozó azonosítója. Az email listában ez az id
mező.
A levél szöveges részébe behelyettesítendő tartalom. A szöveges tartalomba a [mssys_text_content_part]
mezőkódot kell elhelyezni.
A levél HTML részébe behelyettesítendő tartalom. A HTML tartalomba a [mssys_html_content_part]
mezőkódot kell elhelyezni.
Válasz
Válasz sikeres hívás esetén:
Visszaadja az elküldött levelek számát.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
1
Ha a küldés sikertelen a válasz üres string illetve a megfelelő HTTP hibakód lesz.
Megjegyzések
0 megjegyzés
Cikk zárolt megjegyzésekkel szemben.