Cikkek ebben a szekcióban

Feliratkozók kezelése

Király-Páter Csilla
  • Frissítve
Követés

A bejegyzés tartalma:

  1. Feliratkozó hozzáadása
  2. Feliratkozó módosítása
  3. Feliratkozók kötegelt módosítása
  4. Adatmódosító űrlap linkje
  5. Landing oldal linkje
  6. Feliratkozók adatainak lekérdezése
  7. Szegmens(ek) feliratkozóinak lekérdezése
  8. Adatok lekérdezése XML formátumban
  9. Feliratkozó leiratkoztatása
  10. Feliratkozó törlése
  11. Lista feliratkozóinak száma
  12. Szegmensben lévő feliratkozók száma
  13. 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:
POST
https://api.salesautopilot.com/subscribe/<nl_id>/form/<ns_id>
 
Paraméterek:
<nl_id>

E-mail lista azonosítója amelyhez a feliratkozót hozzá szeretné adni.

<ns_id>

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:
PUT
https://api.salesautopilot.com/update/<nl_id>/form/<ns_id>/record/<id>
 
Paraméterek:
<nl_id>

Annak az email listának az azonosítója, amelyben a módosítandó feliratkozó szerepel.

<ns_id>

Adatmódosító űrlap azonosítója

<id>

A módosítandó feliratkozó azonosítója

 
Adatmódosítás egy adott mező értéke alapján:
PUT
https://api.salesautopilot.com/update/<nl_id>/form/<ns_id>/field/<field_name>/value/<field_value>
 
Paraméterek:
<nl_id>

Annak az email listának az azonosítója, amelyben a módosítandó feliratkozók szerepelnek.

<ns_id>

Adatmódosító űrlap azonosítója

<field_name>

A mező neve amely értéke meghatározza a módosítandó feliratkozókat.

<field_value>

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:
PUT
https://api.salesautopilot.com/update/<nl_id>/form/<ns_id>
 
Paraméterek:
<nl_id>

Annak az email listának az azonosítója, amelyben a módosítandó feliratkozók szerepelnek.

<ns_id>

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:
PUT
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.

POST
https://api.salesautopilot.com/batchupdate/<listID>
 
Paraméterek:
<listID>

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.

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:
GET
https://api.salesautopilot.com/list/<nl_id>
 
Paraméterek:
<nl_id>

Az e-mail lista azonosítója amelyből le szeretnénk kérdezni.

 
Egy adott feliratkozó lekérése azonosító alapján:
GET
https://api.salesautopilot.com/list/<nl_id>/record/<id>
 
Paraméterek:
<nl_id>

Az e-mail lista azonosítója amelyből le szeretnénk kérdezni.

<id>

A feliratkozó azonosítója amely adatait lekérdezzük.

 
Feliratkozók lekérése adott mező értéke alapján:
GET
https://api.salesautopilot.com/list/<nl_id>/field/<field_name>/value/<field_value>
 
Paraméterek:
<nl_id>

Az e-mail lista azonosítója amelyből le szeretnénk kérdezni.

<field_name>

Mező neve amely értéke alapján le szeretnénk kérdezni a feliratkozókat.

<field_value>

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:
POST
https://api.salesautopilot.com/list/<nl_id>
 
POST
https://api.salesautopilot.com/list/<nl_id>/order/<orderfield>/<order_dir>/<limit>
 
Paraméterek:
<nl_id>

Az e-mail lista azonosítója amelyből le szeretnénk kérdezni.

 
Opcionális paraméterek:
<orderfield>

Milyen mező alapján legyen sorbarendezve az eredmény. A mező nevét kell megadni.

<orderdir>

A sorrend iránya. asc: növekvő sorrend, desc: csökkenő sorrend.

<limit>

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:
POST
https://api.salesautopilot.com/filteredlist/<nl_id>
 
POST
https://api.salesautopilot.com/filteredlist/<nl_id>/order/<orderfield>/<order_dir>/<limit>
 
Paraméterek:
<nl_id>

Az e-mail lista azonosítója amelyből le szeretnénk kérdezni.

 
Opcionális paraméterek:
<orderfield>

Milyen mező alapján legyen sorbarendezve az eredmény. A mező nevét kell megadni.

<orderdir>

A sorrend iránya. asc: növekvő sorrend, desc: csökkenő sorrend.

<limit>

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]
A szegmens azonosítóját úgy tudja megjeleníteni, hogy a szegmensek listáján a szerkesztés gomb fölé viszi az egérkurzort.

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:
POST
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:
GET
https://api.salesautopilot.com/unsubscribe/<nl_id>/record/<id>
 
Paraméterek:
<nl_id>

E-mail lista azonosítója amelyről a feliratkozót le szeretné iratkoztatni.

<id>

A feliratkozó azonosítója akit le szeretne iratkoztatni.

 
Kérés:
GET
https://api.salesautopilot.com/unsubscribe/<nl_id>/email/<email>
 
Paraméterek:
<nl_id>

E-mail lista azonosítója amelyről a feliratkozót le szeretné iratkoztatni.

<email>

A feliratkozó e-mail címe akit le szeretne iratkoztatni.

 
Kérés:
GET
https://api.salesautopilot.com/unsubscribe/<nl_id>/field/<field_name>/value/<value>
 
Paraméterek:
<nl_id>

E-mail lista azonosítója amelyről a feliratkozót le szeretné iratkoztatni.

<field>

Mező neve ami alapján beazonosítja a feliratkozót.

<value>

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:
DELETE
https://api.salesautopilot.com/delete/<nl_id>/record/<id>
 
Paraméterek:
<nl_id>

E-mail lista azonosítója amelyből a feliratkozók törölni szerentné.

<id>

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:
GET
https://api.salesautopilot.com/listtotalcount/<nl_id>
 
Paraméterek:
<nl_id>

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:
GET
https://api.salesautopilot.com/getsegmentnum/<nls_id>
 
Paraméterek:
<nls_id>

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:
POST
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:
send_id

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.

contactid

A feliratkozó azonosítója. Az email listában ez az id mező.

mssys_text_content_part

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.

mssys_html_content_part

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.

Kapcsolódó cikkek

Megjegyzések

0 megjegyzés

Cikk zárolt megjegyzésekkel szemben.