MailMaster API dokumentáció

1 Hírlevél feliratkozás kezelése saját domain-en

1.1 Háttér

A MarketingSzoftverek rendszer lehetőséget ad hírlevél feliratkozások kezelésére saját domain-en futó szkriptből – szaknyelven távoli eljárás hívással. Ez a gyakorlatban azt jelenti, hogy az ügyfél webalkalmazása interneten keresztül felveszi a kapcsolatot a MarketingSzoftverek szerverén található alkalmazással. A megoldás a POST metódussal adja át a paramétereket a MarketingSzoftverek szerverén futó szkript-nek, amely elvégzi a paraméterek alapján a hírlevél listába történő felíratást - vagy az egyéb műveletet.

1.2 Működés

1.2.1 Távoli szkript

A feliratkozás kezelését az alábbi elérésű szkript végzi:
http://api.marketingszoftverek.hu/nl-remote-subscribe.php

1.2.2 Paraméterek és meghívás

Az átadandó paramétereket asszociatív tömbbe kell szervezni.

Kötelezően átadandó paraméterek

mssys_formid = az űrlap MailMaster API kulcsa, az űrlap adatlapján található.
email = a feliratkozó e-mail címe.

A többi paraméter neve az e-mail lista mezőinek neve, értéke pedig a mező feliratkozóhoz tartozó értéke legyen.

A szöveg mezők ISO-8859-2 karakterkódolással legyenek megadva. Ettől eltérő karakterkódolás esetén, a paraméterek közé fel kell venni a character-encoding paramétert és értékének pedig a megfelelő karakterkódolás nevét kell megadni (pl.: character-encoding = ’UTF-8’).

IP cím alapján történő földrajzi adatmeghatározás esetén a feliratkozó IP címét át kell adni az mssys_ipaddress paraméterben. A feliratkozó IP címet Apache/PHP webszerver esetében általában a $_SERVER['REMOTE_ADDR'] változóból ki lehet olvasni.

Példa a paraméterek asszociatív tömbbe szervezésére:

        <?php
          $param = array( 
            'mssys_formid' => 'lkjaHA45Ahshsfdglm', 
            'email'  => 'info@emesz.hu' 
          ); 
        ?>

Ezután a tömb minden egyes elemének értékét urlencode-dal kódoljuk és előállitjuk a paramétersztringet.

Példa a paramétersztring előállítására:

        <?php
	  $request = "";
	  foreach($param as $key => $value) {
            $request .= $key.'='.urlencode($value).'&';
          }
          $request = rtrim($request, '&');
        ?>

A MarketingSzoftverek URL-jét megnyitjuk távoli eljáráshívással és POST metódussal átadjuk a paraméterstringet.

Példa az URL megnyitására:

        <?php
          $ch = curl_init("http://api.marketingszoftverek.hu/nl-remote-subscribe.php"); 
          curl_setopt($ch, CURLOPT_HEADER, 0);
          curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
          curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
          $response = curl_exec($ch);
          curl_close ($ch);
        ?>

1.2.3 Visszatérési érték

A távoli eljáráshívás visszatérési értéke egy XML formátumú dokumentum, amely tartalmazza a feliratkozó azonosítóját a e-mail listában.
Ha a feliratkozó azonosítója -1, akkor hiba történt az eljárás során (pl.: hibás a feliratkozó e-mail címe vagy a feliratkozó e-mail címe már szerepel az e-mail listában és az e-mail cím egyedi azonosító).
Az XML dokumentum felépítése a következő:

        
        <?xml version="1.0"?>
            <subscriber>
              <details>
                <id>7</id>

              </details>
            </subscriber>

Példa az XML fájl feldolgozására (az összes szereplő változó kiiratása, majd a feliratkozó ID-jának kiiratása):


        <?php
          $xml = simplexml_load_string($response);
          print "<pre>";
          print_r($xml);
          print "</pre>";
          print $xml->details[0]->id;
        ?>

2 Adatfrissítés kezelése saját domain-en

2.1 Háttér

A MarketingSzoftverek rendszere lehetőséget ad távoli eljáráshívással a hírlevél feliratkozók adatainak frissítésére. A megoldás biztosítja, hogy egyszerre egy e-mail listában, akár egyidejűleg több feliratkozó bármely adata frissítésre kerüljön.
A megoldás a POST metódussal adja át a paramétereket a MarketingSzoftverek szerverén futó szkript-nek amely elvégzi a paraméterek alapján a hírlevél feliratkozó frissítését.

2.2 Működés

2.2.1 Távoli szkript

A frissítés kezelését az alábbi elérésű szkript végzi:
http://api.marketingszoftverek.hu/nl-remote-update.php

2.2.2 Paraméterek és meghívás

Az átadandó paramétereket asszociatív tömbbe kell szervezni.

Kötelezően átadandó paraméterek

mssys_formid = az űrlap MailMaster API kulcsa, az űrlap adatlapján található.

A frissítendő feliratkozók (gyakorlatilag adatábázis rekordok) körét két paraméter határozza meg (opcionálisan több paraméter is megadható a logikai kifejezés szűkítésére):

id_field = annak a mezőnek a neve ami alapján beazonosítunk egy feliratkozót, vagy a feliratkozók körét. Pl. email, ha e-mail cím alapján azonosítjuk a feliratkozót.
id_value = a mező értéke amire szűrjük a frissítendő feliratkozók körét. Pl. lehet egy konkrét e-mail cím, de lehet olyan értéke, amely azt jelenti, hogy azokat frissítse, akinek az e-mail címe marketingszoftverek.hu-ra végződik. Ebben az esetben az SQL szintaxisának megfelelő wildcard karakterrel adjuk meg a mező szűrőértékét: ’%marketingszoftverek.hu’.
is_report = ha 1 az értéke, akkor küld értesítést az adatfrissítésről a megfelelő felhasználóknak

A biztonság miatt az adatfrissítés csak egy MarketingSzoftverek felhasználó felhasználónevével és jelszavával lehetséges, akinek jogosultsága van MailMaster modulhoz. Ezt az alábbi két paraméterrel lehet megadni:

auth_username = felhasználó neve
auth_password = felhasználó jelszava

Opcionálisan átadható paraméterek

id_cond = első frissítési feltétel relációja, azaz a mezőnév és érték közötti reláció. Pl. subdate < '2010-09-01 00:00:00' Lehetséges értéke: =, <, >, <=, >=, <>

A frissítendő rekordok körét meghatározó második feltételt az alábbi paraméterekkel lehet definiálni:

id_field1 = második feltétel mezőneve
id_cond1 = második feltétel relációja
id_value1 = második feltétel értéke

Ha meg van adva második feltétel, akkor az az első feltételhez mindig logikai ÉS kifejezéssel lesz kapcsolva, azaz a frissítendő rekordok körét a két feltétel együttesen határozza meg.

Biztonsági okokból célszerű egy külön felhasználót létrehozni erre a célra, akinél be van kapcsolva a MailMaster modul elérése.

A további paraméterek neve az e-mail lista frissítendő mezőinek neve, értéke pedig a mező új értéke legyen.

A szöveg mezők ISO-8859-2 karakterkódolással legyenek megadva. Ettől eltérő karakterkódolás esetén, a paraméterek közé fel kell venni a character-encoding paramétert és értékének pedig a megfelelő karakterkódolás nevét kell megadni. (pl.: character-encoding = ’UTF-8’).

A paramétereket asszociatív tömbbe kell rendezni, annak értékeit urlencode-dal kódolni, majd az így előállított paramétersztringet cURL-lel megnyitni.

Példa a paraméterek asszociatív tömbbe szervezésére, urlecode-dal történő átalakítására majd a cURL távoli eljáráshívásra:

        <?php
          $param = array( 
            'mssys_formid'        =>  'lkjaHA45Ahshsfdglm', 
            'id_field'            =>  'email',
            'id_value'            =>  '%@emesz.hu',
            'is_report'           =>  '1',
            'auth_username'       =>  'felhasználó neve',
            'auth_password'       =>  'felhasználó jelszava',
            'character-encoding'  =>  'UTF-8'
          );
		  
          $request = "";
          foreach($param as $key => $value) {
            $request .= $key.'='.urlencode($value).'&';
          }
          
          $request = rtrim($request, '&');
          $ch = curl_init("http://api.marketingszoftverek.hu/nl-remote-update.php"); 
          curl_setopt($ch, CURLOPT_HEADER, 0);
          curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
          curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
          $response = curl_exec($ch);
          curl_close ($ch);
        ?>

2.2.3 Visszatérési érték

A távoli eljáráshívás visszatérési értéke egy XML formátumú dokumentum, amely tartalmazza, hogy hány feliratkozó adata került módosításra.
Az XML dokumentum felépítése a következő:


        
        <?xml version="1.0"?>
            <subscriber>
              <details>
                <updated_count>5</updated_count>

              </details>
            </subscriber>

Példa az XML fájl feldolgozására (módosított rekordok számának kiíratása):


        <?php    
          $xml = simplexml_load_string($response);
          print "A frissített mezők száma: ".$xml->details->updated_count;
        
        ?>

3 Feliratkozó adatainak lekérdezése saját domain-en

3.1 Háttér

A MarketingSzoftverek rendszere lehetőséget ad távoli eljáráshívással a hírlevél feliratkozó adatainak lekérdezésére. A megoldás biztosítja, hogy egyszerre egy e-mail listában, akár egy feliratkozó összes adata lekérdezhető legyen.
A megoldás a GET metódussal adja át a paramétereket a MarketingSzoftverek szerverén futó szkript-nek amely elvégzi a paraméterek alapján a hírlevél feliratkozó adatainak lekérdezését.

3.2 Működés

3.2.1 Távoli szkript

Az adatlekérdezés kezelését az alábbi elérésű szkript végzi:
http://api.marketingszoftverek.hu/nl-remote-get-data.php

3.2.2 Paraméterek és meghívás

Az átadandó paramétereket asszociatív tömbbe kell szervezni.

Kötelezően átadandó paraméterek

mssys_formid = az űrlap MailMaster API kulcsa, az űrlap adatlapján található.

A lekérdezendő feliratkozót kétféleképp lehet azonosítani:

Ha az e-mail címe által azonosítunk, akkor paraméterként át kell adni azt:
- email = azon feliratkozó e-mail címe, akinek az adatait lekérdezzük.
Adott mező alapján azonosítunk, akkor paraméterként át kell adni az(oka)t:
- id_field = mező neve.
- id_value = érték, amit keresünk.

Amennyiben több feliratkozó is megfelel a lekérdezésnek, az első - kritériumnak megfelelő - feliratkozó adatait kapjuk eredményül.

A biztonság miatt a lekérdezés csak egy MarketingSzoftverek felhasználó felhasználónevével és jelszavával lehetséges, akinek jogosultsága van MailMaster modulhoz. Ezt az alábbi két paraméterrel lehet megadni:

auth_username = felhasználó neve
auth_password = felhasználó jelszava

Biztonsági okokból célszerű egy külön felhasználót létrehozni erre a célra, akinél be van kapcsolva a MailMaster modul elérése.

A paramétereket asszociatív tömbbe kell rendezni, annak értékeit urlencode-dal kódolni, majd az így előállított paramétersztringet cURL-lel megnyitni.

Példa a paraméterek asszociatív tömbbe szervezésére, urlecode-dal történő átalakítására majd a cURL távoli eljáráshívásra:

        <?php
          $param = array( 
            'mssys_formid'        =>  'lkjaHA45Ahshsfdglm', 
            'email'               =>  'info@emesz.hu',
            'auth_username'       =>  'felhasználó neve',
            'auth_password'       =>  'felhasználó jelszava',
            );
          
	  $request = "";
          foreach($param as $key => $value) {
            $request .= $key.'='.urlencode($value).'&';
          }
          
          $request = rtrim($request, '&');
          $ch = curl_init("http://api.marketingszoftverek.hu/nl-remote-get-data.php"); 
          curl_setopt($ch, CURLOPT_HEADER, 0);
          curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
          curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
          $response = curl_exec($ch);
          curl_close ($ch);
        
        ?>

3.2.3 Visszatérési érték

A távoli eljáráshívás visszatérési értéke egy XML dokumentum,amely tartalmazza a feliratkozó(k) adatait. A visszatérési érték kódolása mindig UTF-8. Ezt szükség esetén át lehet alakítani a fogadó oldalon bármilyen más karakterkódolásra.
Az XML dokumentum felépítése a következő:

        

        <?xml version="1.0"?>
            <subscriberdata>
              <id>5</id>
              <subdate>2009-04-20 10:34:22</subdate>

              <subdate>2009-04-20 10:34:22</subdate>
              <active>2009-04-20 10:34:22</active>
              <firstupdate>2009-04-20 11:39:28</firstupdate>
              <lastupdate>2009-04-20 11:44:02</lastupdate>

              <email>valaki@valami.hu</email>
              <mssys_cookie>123331890044634097</mssys_cookie>
              <mssys_secure_id>xeJcsb0trU/IRc/FWQ==</mssys_secure_id>
              <mssys_lastname>Nebáncs</mssys_lastname>

              <mssys_firstname>Virág</mssys_firstname>
            </subscriberdata>

Példa a visszatérési érték megjelenítésére:

        <?php
            $xml = simplexml_load_string($response);
            print "Azonosító:  ".$xml->id."<br />";
            print "Vezetéknév: ".$xml->mssys_lastname."<br />";
            print "Keresztnév: ".$xml->mssys_firstname."<br />";
            print "E-mail cím: ".$xml->email;
        
        ?>

Amennyiben a visszakapott értékeket nem közvetlenül kiiratni akarjuk, hanem tovább kívánunk azokkal dolgozni, akkor érdemes azokat egy tömbbe eltárolni, melyet a következőképpen tehetünk meg:

		<?php
			$xml = simplexml_load_string($response);
			$xmlarray = get_object_vars($xml);
			print "Azonosító:  ".$xmlarray['id'];
		?>

4 Adott időszakban feliratkozottak e-mail címeinek lekérdezése

4.1 Háttér

A MarketingSzoftverek rendszere lehetőséget ad távoli eljáráshívással egy adott hírlevélre, adott időszakban (adott napon vagy két dátum között) feliratkozottak e- mail címeinek lekérdezésére.
A megoldás a POST metódussal adja át a paramétereket a MarketingSzoftverek szerverén futó szkript-nek amely elvégzi a paraméterek alapján a hírlevél feliratkozó adatainak lekérdezését.

4.2 Működés

4.2.1 Távoli szkript

Az adatlekérdezés kezelését az alábbi elérésű szkript végzi:
http://api.marketingszoftverek.hu/nl-remote-get-data-bysubdate.php

4.2.2 Paraméterek és meghívás

Az átadandó paramétereket asszociatív tömbbe kell szervezni.

Kötelezően átadandó paraméterek

mssys_formid = az űrlap MailMaster API kulcsa, az űrlap adatlapján található.
start_subdate = az a dátum amely naptól kezdve feliratkozókat listázzuk. A dátum formátuma: [YYYYMMDD].
end_subdate = az a dátum amely napig feliratkozókat listázzuk. A dátum formátuma: [YYYYMMDD].
fieldlist = az e-mail lista azon mezői amelyek értékét szeretné lekérdezni. Megadása: mezőnevek, vesszővel tagolva. Pl.: id,email,mssys_firstname
Megadása nem kötelező. Ha nincs megadva akkor csak az e-mail cím kerül listázásra.

(Ha adott napon feliratkozókat listázzuk, akkor a start_subdate és end_subdate értéke ugyanaz a nap legyen.)

auth_username = felhasználó neve
auth_password = felhasználó jelszava

Biztonsági okokból célszerű egy külön felhasználót létrehozni erre a célra, akinél be van kapcsolva a MailMaster modul elérése.

A paramétereket asszociatív tömbbe kell rendezni, annak értékeit urlencode-dal kódolni, majd az így előállított paramétersztringet cURL-lel megnyitni.

Példa a paraméterek asszociatív tömbbe szervezésére, urlecode-dal történő átalakítására majd a cURL távoli eljáráshívásra:

        <?php
          $param = array( 
            'mssys_formid'        =>  'lkjaHA45Ahshsfdglm',
            'start_subdate'       =>  '20090315',
            'end_subdate'         =>  '20090331',
            'auth_username'       =>  'felhasználó neve',
            'auth_password'       =>  'felhasználó jelszava'
          );
          
	  $request = "";
          foreach($param as $key => $value) {
            $request .= $key.'='.urlencode($value).'&';
          }
          
          $request = rtrim($request, '&');
          $ch = curl_init("http://api.marketingszoftverek.hu/nl-remote-get-data-bysubdate.php"); 
          curl_setopt($ch, CURLOPT_HEADER, 0);
          curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
          curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
          $response = curl_exec($ch);
          curl_close ($ch);
        
        ?>

4.2.3 Visszatérési érték

A távoli eljáráshívás visszatérési értéke egy XML dokumentum, amely tartalmazza a feliratkozók adatait. Ha a fieldlist paraméter nem volt definiálva, akkor az alábbi formátumú XML dokumentumot adja vissza az API hívás.
Az XML dokumentum felépítése a következő:


        
        <?xml version="1.0"?>
            <subscribers>
              <email>Array(
                    [0] => valaki@valami.hu,
                    [1] => valaki_mas@valami.hu
                  )
              </email>
            </subscribers>

Ha a fieldlist paraméter definiálva volt, akkor az alábbi felépítésű XML dokumentumot adja vissza az API hívás:


        
        <?xml version="1.0"?>
            <subscribers>
              <subscriberdata>
              	<id>1</id>
              	<email>valaki@valami.hu</email>
              </subscriberdata>
              <subscriberdata>
              	<id>2</id>
              	<email>valaki_mas@valami.hu</email>
              </subscriberdata>
            </subscribers>

Példa a visszatérési érték megjelenítésére:

        <?php
            $xml = simplexml_load_string($response);
            $i=0;
            foreach($xml as $entity) {
              print "<br />email: ".$xml->email[$i];
              $i++;
            }
        
        ?>

5 Leiratkozás kezelése saját domain-en

5.1 Háttér

A MarketingSzoftverek rendszere lehetőséget ad távoli eljáráshívással a hírlevél feliratkozók leiratására. Az így történt leiratkozáskor is elküldésre kerül a leiratkozáskor típusú időzítéssel beállított levél.
A megoldás a POST metódussal adja át a paramétereket a MarketingSzoftverek szerverén futó szkript-nek amely elvégzi a paraméterek alapján a hírlevél feliratkozó leiratását.

5.2 Működés

5.2.1 Távoli szkript

A leiratkozás kezelését az alábbi elérésű szkript végzi:
http://api.marketingszoftverek.hu/nl-remote-unsubscribe.php

5.2.2 Paraméterek és meghívás

Az átadandó paramétereket asszociatív tömbbe kell szervezni.

Kötelezően átadandó paraméterek

nl_id = e-mail lista azonosítója. Az e-mail lista adatai képernyőn a Lista azonosítója sorban található érték.
nud_id = az e-mail listán szereplő azon feliratkozó azonosítója akinek a státuszát leiratkozottra kell állítani.

auth_username = felhasználó neve
auth_password = felhasználó jelszava

Biztonsági okokból célszerű egy külön felhasználót létrehozni erre a célra, akinél be van kapcsolva a MailMaster modul elérése.

A paramétereket asszociatív tömbbe kell rendezni, annak értékeit urlencode-dal kódolni, majd az így előállított paramétersztringet cURL-lel megnyitni.

Példa a paraméterek asszociatív tömbbe szervezésére, urlecode-dal történő átalakítására majd a cURL távoli eljáráshívásra:

        <?php
          $param = array( 
            'nl_id'               =>  '1257',
            'nud_id'              =>  '39',
            'auth_username'       =>  'felhasználó neve',
            'auth_password'       =>  'felhasználó jelszava'
          );
          
	  $request = "";
          foreach($param as $key => $value) {
            $request .= $key.'='.urlencode($value).'&';
          }
          
          $request = rtrim($request, '&');
          $ch = curl_init("http://api.marketingszoftverek.hu/nl-remote-unsubscribe.php"); 
          curl_setopt($ch, CURLOPT_HEADER, 0);
          curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
          curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
          $response = curl_exec($ch);
          curl_close ($ch);
        
        ?>

5.2.3 Visszatérési érték

A távoli eljáráshívás visszatérési értéke egy XML dokumentum, amelynek tartalma - sikeres leiratkozás esetén - 1, egyéb esetben 0.
Az XML dokumentum felépítése a következő:


        
        <?xml version="1.0"?>
            <subscribers>
              <unsubscribed>1</unsubscribed>
            </subscribers>

Példa az XML fájl feldolgozására:

        <?php
            $xml = simplexml_load_string($response);
            if ($xml->unsubscribed == '1') {
              print "Sikeres leiratkozás!";
            }
        
        ?>

Tudásbázis:
- Összetett rendszerek készítése

MarketingSzoftverek Tudásbázis

Belépés

Tudásbázis témák

MailMaster bevezető tréning

MailMaster API dokumentáció

1 Hírlevél feliratkozás kezelése saját domain-en

1.1 Háttér

1.2 Működés

1.2.1 Távoli szkript

1.2.2 Paraméterek és meghívás

1.2.3 Visszatérési érték

2 Adatfrissítés kezelése saját domain-en

2.1 Háttér

2.2 Működés

2.2.1 Távoli szkript

2.2.2 Paraméterek és meghívás

2.2.3 Visszatérési érték

3 Feliratkozó adatainak lekérdezése saját domain-en

3.1 Háttér

3.2 Működés

3.2.1 Távoli szkript

3.2.2 Paraméterek és meghívás

3.2.3 Visszatérési érték

4 Adott időszakban feliratkozottak e-mail címeinek lekérdezése

4.1 Háttér

4.2 Működés

4.2.1 Távoli szkript

4.2.2 Paraméterek és meghívás

4.2.3 Visszatérési érték

5 Leiratkozás kezelése saját domain-en

5.1 Háttér

5.2 Működés

5.2.1 Távoli szkript

5.2.2 Paraméterek és meghívás

5.2.3 Visszatérési érték

Mennyire volt hasznos Önnek az oldal tartalma?

Köszönjük visszajelzését!

Sikertelen küldés!