SmartEmailing 2.0 API Popis způsobu používání služby

SmartEmailing 2.0 API Popis způsobu používání služby 1

Historie dokumentu Datum Popis 12.03.2014 Created 1.0 11.04.2014 Added getallunsubscribed and typping errors 24.04.2014 Added ContactLists getcontacts and short info 2

Obsah 1. Základní informace 1.1 Zasílání XML requestů 1.2 Zabezpečení spojení 1.3 Vzorový příklad připojení z PHP 1.4 Jak testovat XML požadavky? 2. Podporované funkce 2.1 Kontrola přihlašovacích údajů 2.2 Zjištění ID vlastního účtu 2.3 Smazání jednoho seznamu kontaktů 2.4 Získání všech seznamů kontaktů pod účtem 2.5 Získání jednoho seznamu kontaktů pod účtem 2.6 Vytvoření seznamu kontaktů 2.7 Získání struktury vlastního pole 2.8 Kampaně: Získání všech kampaní pod účtem 2.10 Kampaně: Smazání určité kampaně 2.11 Kampaně: Vytvoření kampaně 2.12 Kampaně: Update změna kampaně 2.13 Statistika kampaní: Získat vrácené kontakty dle kampaně 2.14 Statistika kampaní: Získat kontakty, které neotevřely danou kampaň 2.15 Statistika kampaní: Získat kontakty, které se z dané kampaně odhlásily 2.16 Statistika kampaní: Získat kontakty, které klikly na odkaz v dané kampani 2.17 Statistika kampaní: Získat kontakty, které otevřely danou kampaň 2.18 Statistika kampaní: Získat přehled pro celou kampaň 2.19 Statistika SmartKampaně: Získat odhlášené kontakty dle SmartKampaně 2.21 Statistika SmartKampaně: Získat kontakty, které otevřely danou SmartKampaň 2.22 Statistika SmartKampaně: Získat kontakty, které klikly na odkaz v dané SmartKampani 2.23 Statistika SmartKampaní: Získat vrácené kontakty dle SmartKampaně 2.24 Statistika SmartKampaně: Získat přehled pro celou SmartKampaň 2.25 Kontakt: Získat všechny kontakty 2.24 Kontakt: Získat jeden kontakt 2.25 Kontakt: Vytvořit, update kontakt 2.26 Kontakt: Smazat kontakt 2.27 Kontakt: Získat všechny odhlášené kontakty 2.28 Seznamy kontaktů: Získat kontakty dle seznamu kontaktů 3

1. Základní informace SmartEmailing API je služba umožňující uživatelům pomocí zasílaných XML požadavků vzdáleně spouštět funkce systému SmartEmailing. SmartEmailing poskytuje možnost automaticky aktualizovat a používat systém bez nutnosti fyzického přístupu. Použitím obecného a ve většině programovacích jazyků podporovaného značkovacího jazyka můžete propojit SmartEmailing s prakticky každou aplikací. Následují obecné poznámky týkající se celého systému: systém standardně pracuje s kódováním UTF 8 v rámci aplikace se pracuje s unikátním kontaktem, který je přiřazován do vícero sezanamů, kde může mít unikátní stav 1.1 Zasílání XML requestů Veškerá komunikace je realizovaná pomocí HTTP protokolu. Žádosti jsou odesílány na předem určenou adresu jako POST požadavek obsahující XML feed s potřebnými údaji. Uživatelské jméno pro XML API je stejné jako přihlašovací jméno do webového prostředí, XML token Vám bude zaslán po objednání služby. URL API je https://app.smartemailing.cz/api/v2 V příkladech v tomto dokumentu budou jako autentizační údaje použity fiktivní přístupy: URL: https://app.smartemailing.cz/api/v2 USERNAME: USERNAME TOKEN: TOKEN Není li uvedeno jinak, jsou všechny uvedené položky v zasílané XML žádosti povinné. U těchto položek také záleží na pořadí, ve kterém jsou zaslány. Je li u daného uzlu uvedeno, že je vyžadováno, znamená to, že systém očekává neprázdnou hodnotu (tedy např. i 0). 1.2 Zabezpečení spojení Pro komunikaci s API je využíváno výlučně šifrované spojení. Proto pro komunikaci pro API používejte výlučně odkaz se s na konci. URL API je https://app.smartemailing.cz/api/v2 4

1.3 Vzorový příklad připojení z PHP Každá metoda bude doplněna o vzorový příklad zápisu v programovacím jazyku PHP. Pro práci s PHP je třeba mít kromě metody uložen i soubor base.php. Kompletní vzorové kódy jsou ke stažení ZDE. Obsahuje: <?php $token = 'TOKEN'; $username = 'LOGIN'; function v($result) { echo $result; //print_r($result); die(); } function sendrequest($xml) { $ch = curl_init('https://app.smartemailing.cz/api/v2'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, $xml); $result = curl_exec($ch); if ($result === false) { echo "Chyba v zasilani XML requestu!"; } else { header ("Content Type:text/xml"); v($result); /** @noinspection PhpUsageOfSilenceOperatorInspection */ $xml_doc = @simplexml_load_string($result); // intentionally @ if (!$xml_doc) { echo "ERR in request". PHP_EOL; v($result); } 5

PHP_EOL; echo PHP_EOL. $result. PHP_EOL. ' '. echo 'Status is '. $xml_doc >status. PHP_EOL; } } if ($xml_doc >status == 'SUCCESS') { print_r($xml_doc >data); } else { echo $xml_doc >errormessage. PHP_EOL; } 1.4 Jak testovat XML požadavky? Pokud chcete testovat XML jednoduše a rychle. Doporučuji nainstalovat plugin do Google Chrome s názvem Advanced rest client. 2. Podporované funkce 2.1 Kontrola přihlašovacích údajů S touto funkcí je možno zkontrolovat správnost údajů a zda nám napojení na API funguje. Vzor XML: <requesttype>users</requesttype> <requestmethod>testcredentials</requestmethod> Vzor PHP: $xml = ' 6

<username>'.$username.'</username> <usertoken>'.$token.'</usertoken> <requesttype>users</requesttype> <requestmethod>testcredentials</requestmethod> '; Když dotaz projde správně, vrátí se: <status> SUCCESS </status> Authentication successful. </data> Pokud dojde k chybě údajů: <status> FAILED </status> <errormessage> Invalid credentials </errormessage> 2.2 Zjištění ID vlastního účtu S touto funkcí je možno zjistit ID účtu, na které máme k dispozici údaje API. Požadavek v XML: 7

<requesttype>users</requesttype> <requestmethod>getid</requestmethod> Požadavek v PHP: $xml = ' <username>'.$username.'</username> <usertoken>'.$token.'</usertoken> <requesttype>users</requesttype> <requestmethod>getid</requestmethod> '; Když dotaz projde správně, vrátí se: <status> SUCCESS </status> 2399 </data> 2.3 Smazání jednoho seznamu kontaktů Pomocí této metody můžeme smazat seznam kontaktů, pokud známe jeho ID. Vzorové XML: <requesttype>contactlists</requesttype> 8

<requestmethod>delete</requestmethod> <id>30</id> <removecontacts>1</removecontacts><! optional > Vzorové PHP: $xml = ' <username>'. $username. '</username> <usertoken>'. $token. '</usertoken> <requesttype>contactlists</requesttype> <requestmethod>delete</requestmethod> <id>30</id> <removecontacts>1</removecontacts><! optional > '; Když dotaz projde správně, vrátí se: <status> SUCCESS </status> 1 </data> 2.4 Získání všech seznamů kontaktů pod účtem Získáme tak výpis všech seznamů kontaktů, které jsou pod účtem s danými přístupy. Dále z výpisu můžeme využít tyto informace: ID seznamu, Veřejný název seznamu, 9

Datum vytvoření, Výpis vlastních polí, Poznámku, Jméno vlastníka seznamu, E mail vlastníka seznamu, E mail pro odpovědi, Podpis vlastníka seznamu, ID segmentů. Vzorové XML: <username>login</username> <requesttype>contactlists</requesttype> <requestmethod>getall</requestmethod> Vzorové PHP: $xml = ' <username>'.$username.'</username> <usertoken>'.$token.'</usertoken> <requesttype>contactlists</requesttype> <requestmethod>getall</requestmethod> '; Když dotaz projde správně, vrátí se: <status>success</status> <name>ab</name><publicname></publicname><notes></notes><created >2014 02 04 13:22:03</created><alertIn>0</alertIn><alertOut>0</alertOut><trackedD efaultfields>a:3:{i:0;s:12:"emailaddress";i:1;s:4:"cf_ 10

1";i:2;s:4:"cf_3";}</trackedDefaultFields><sendername> Václav Růt</sendername><senderemail>EMAIL</senderemail><replyto>rut.v@seznam.cz</replyto><signature></signature><segment_id></segment_id><id>3</i d><name>test</name><publicname></publicname><notes></not es><created>2014 02 18 16:10:21</created><alertIn>0</alertIn><alertOut>0</alertOut><trackedD efaultfields>a:0:{}</trackeddefaultfields><sendername>václav Růt</sendername><senderemail>rut.v@seznam.cz</senderemail><replyto>ru t.v@seznam.cz</replyto><signature></signature><segment_id></segment_i d><id>4</id> </data> 2.5 Získání jednoho seznamu kontaktů pod účtem Pomocí této metody získáme podrobné informace o jednom účtu kontaktů. K získání této informace je třeba znát ID seznamu kontaktů. Poté dostaneme výpis který bude obsahovat: Veřejný název seznamu, Datum vytvoření, Výpis vlastních polí, Poznámku, Jméno vlastníka seznamu, E mail vlastníka seznamu, E mail pro odpovědi, Podpis vlastníka seznamu, ID segmentů. Pro získání informací z pole <trackeddefaultfields> je třeba zavolat na výpis PHP funkci unserialize(), které tuto informaci rozklíčuje a vrátí PHP value, o unserialize() více info ZDE. Využití částí<alertin> a <alertout> budou zpřístupněny a popsány v dalších verzích dokumentace, jelikož aktuálně není doprogramována celá logika. Vzorové XML: <requesttype>contactlists</requesttype> <requestmethod>getone</requestmethod> 11

<id>number</id> Vzorové PHP: $xml = ' <username>'.$username.'</username> <usertoken>'.$token.'</usertoken> <requesttype>contactlists</requesttype> <requestmethod>getone</requestmethod> <id>number</id> '; Když dotaz projde správně, vrátí se: <status> SUCCESS </status> <name> AB </name> <publicname /> <notes /> <created> 2014 02 04 13:22:03 </created> <alertin> 12

0 </alertin> <alertout> 0 </alertout> <trackeddefaultfields> a:3:{i:0;s:12:"emailaddress";i:1;s:4:"cf_1";i:2;s:4:"cf_3";} </trackeddefaultfields> <sendername> Václav Růt </sendername> <senderemail> rut.v@seznam.cz </senderemail> <replyto> rut.v@seznam.cz </replyto> <signature /> <segment_id /> </data> Když dotaz neprojde správně kvůli špatnému ID seznamu, vrátí se: <status> FAILED </status> <errormessage> contact list does not exist </errormessage> 13

2.6 Vytvoření seznamu kontaktů Tímto způsobem je možno přes API vytvořit seznam kontaktů pod určitým účtem. Pro vytvoření seznamu kontaktů je třeba do XML doplnit tyto informace, bez kterých není vytvoření možné: <username> Uživatelské jméno <usertoken> Token <name> Název seznamu <trackeddefaultfields> Definice vlastních polí <sendername> Jméno odesílatele pro daný seznam kontaktů <senderemail> E mail odesílatele pro daný seznam kontaktů <replyto> E mail pro odpovědi pro daný seznam kontaktů <publicname> Veřejný název, který se zobrazí klientům při odhlašování ze seznamu Vzorové XML: <requesttype>contactlists</requesttype> <requestmethod>create</requestmethod> <name>list po API</name> <trackeddefaultfields>a:2:{i:0;s:7:"updated";i:1;s:11:"blacklisted";} </trackeddefaultfields> <sendername>václav Růt</sendername> <senderemail>vaclav@smartemailing.cz</senderemail> <replyto>vaclav@smartemailing.cz</replyto> <publicname>testovací seznam</publicname> Vzorové PHP: $xml = ' <username>'. $username. '</username> <usertoken>'. $token. '</usertoken> <requesttype>contactlists</requesttype> <requestmethod>create</requestmethod> <name>list po API</name> 14

<trackeddefaultfields>a:2:{i:0;s:7:"updated";i:1;s:11:"blacklisted";} </trackeddefaultfields> <sendername>václav Růt</sendername> <senderemail>vaclav@smartemailing.cz</senderemail> <replyto>vaclav@smartemailing.cz</replyto> <publicname>testovací seznam</publicname> '; Pokud je seznam úspěšně vytvořen, vrací se: <status> SUCCESS </status> <name> List po API </name> <publicname> Testovací seznam </publicname> <notes /> <created> 2014 03 19 13:29:25 </created> <alertin> 0 </alertin> <alertout> 0 </alertout> <trackeddefaultfields> a:2:{i:0;s:7:"updated";i:1;s:11:"blacklisted";} </trackeddefaultfields> <sendername> 15

Václav Růt </sendername> <senderemail> vaclav@smartemailing.cz </senderemail> <replyto> vaclav@smartemailing.cz </replyto> <signature /> <segment_id /> <id> 5 </id> </data> 2.7 Získání struktury vlastního pole Tato funkce vrátí strukturu vlastního pole, abyste věděli, v jakém formátu máte toto vlastní pole posílat, pokud vytváříte kontakt s tímto vlastním polem. Pro úspěšné zaslání requestu je třeba znát: username uživatelské jméno token api klíč id id vlastího pole Vzorové XML: <username>username<username> <requesttype>customfields</requesttype> <requestmethod>describe</requestmethod> <id>41</id> Vzorové PHP: $xml = " 16

<username>{$username}</username> <usertoken>{$token}</usertoken> <requesttype>customfields</requesttype> <requestmethod>describe</requestmethod> <id>41</id> "; Pokud je vše v pořádku a chceme získat strukturu vlastního pole typu radio button, vrátí se toto: <status> SUCCESS </status> <name> asdas </name> <type> radio </type> <options> <id> 1 </id> <customfield_id> 4 </customfield_id> <name> a </name> <order> 0 </order> 17

<id> 2 </id> <customfield_id> 4 </customfield_id> <name> b </name> <order> 1 </order> <id> 3 </id> <customfield_id> 4 </customfield_id> <name> c </name> <order> 2 </order> </options> </data> 2.8 Kampaně: Získání všech kampaní pod účtem Pomocí tohoto dotazu získáme všechny kampaně pod účtem. Vzorové XML: <username>rut.v@seznam.cz</username> 18

<usertoken>zojkbcfwqs7abcg4lo1aeni794jojgvnesyt8cka</usertoken> <requesttype>campaigns</requesttype> <requestmethod>getall</requestmethod> Vzorové PHP: $xml = " <requesttype>campaigns</requesttype> <requestmethod>getall</requestmethod> "; V případě, že požadavek projde správně, vrátí se: <status> SUCCESS </status> <id> 2 </id> <htmlbody> PGh0bWw+CjxoZWFkPgoJPHRpdGxlPjwvdGl0bGU+CjwvaGVhZD4KPGJvZHk+ZGF0ZTwvY m9ket4kpc9odg1spgo= </htmlbody> <textbody> Date </textbody> <title> date </title> 19

<name> date </name> </data> Z tohoto výpisu získáme ID kampaní, Textovou verzi kampaně, Název kampaně, Předmět a HTML kampaně. HTML kód je zakódovaný do BASE64. Pro dekódování a zakódování je možno v PHP použít funkce base64_encode a base64_decode. 2.9 Kampaně: Získání jedné kampaně z pod účtu Stejná metoda jako 2.8, tato je pouze zaměřena na získání dat o jedné určité kampani. Pro získání tohoto výpisu musíme znát ID kampaně, kterou chceme. Vzorové XML: <requesttype>campaigns</requesttype> <requestmethod>getone</requestmethod> <id>11</id> Vzorové PHP: $xml = " <username>{$username}</username> <usertoken>{$token}</usertoken> <requesttype>campaigns</requesttype> <requestmethod>getone</requestmethod> <id>11</id> "; Pokud request projde, dostaneme stejný výpis jako v případě 2.8. 20

2.10 Kampaně: Smazání určité kampaně Touto funkcí můžeme smazat určitou kampaň, pokud známe její ID. Příjlad XML: <username>{$username}</username> <usertoken>{$token}</usertoken> <requesttype>campaigns</requesttype> <requestmethod>delete</requestmethod> <id>75</id> Příklad PHP: $xml = " <username>{$username}</username> <usertoken>{$token}</usertoken> <requesttype>campaigns</requesttype> <requestmethod>delete</requestmethod> <id>75</id> "; Výpis pokud je kampaň úspěšně smazána: <status> SUCCESS </status> 1 </data> 21

2.11 Kampaně: Vytvoření kampaně Pomocí této metody vytvoříme po API novou kampaň. Je třeba naplnit: <htmlbody> HTML <textbody> Texotovou verzi <name> Název <title> Předmět HTML je třeba zakódovat před odesláním requestu do BASE64. Vzorové XML: <requesttype>campaigns</requesttype> <requestmethod>create</requestmethod> <htmlbody>pgh0bww+dqo8agvhzd4ncgk8dgl0bgu+pc90axrszt4ncjwvagvhzd4ncjx hbmsipmtsawtudxqmawfjdxrlo20gemrlpc9hpi48l3rkpg0kcqk8l3rypg0kctwvdgjv ZHk+DQo8L3RhYmxlPg0KPC9ib2R5Pg0KPC9odG1sPg0K</htmlbody> <textbody>textova verze kamapně</textbody> <name>názevkampaně</name> <title>předmět</title> Vzorové PHP: $xml = " <username>{$username}</username> <usertoken>{$token}</usertoken> <requesttype>campaigns</requesttype> <requestmethod>create</requestmethod> <htmlbody>pgh0bww+dqo8agvhzd4ncgk8dgl0bgu+pc90axrszt4ncjwvagvhzd4ncjx 22

hbmsipmtsawtudxqmawfjdxrlo20gemrlpc9hpi48l3rkpg0kcqk8l3rypg0kctwvdgjv ZHk+DQo8L3RhYmxlPg0KPC9ib2R5Pg0KPC9odG1sPg0K</htmlbody> <textbody>textova verze kamapně</textbody> <name>názevkampaně</name> <title>předmět</title> "; Pokud je vše v pořádku, vrátí se: <status> SUCCESS </status> 9 </data> 2.12 Kampaně: Update změna kampaně Touto metodou můžeme provést změnu, update již existující kampaně. Pro úspěšnou změnu je třeba znát ID kampaně, kterou chceme měnit. Vzorové XML: <requesttype>campaigns</requesttype> <requestmethod>update</requestmethod> <id>80</id> <htmlbody>html</htmlbody> <textbody>text VERZE</textbody> <name>new NAME OF CAMPAIGN</name> <title>new SUBJECT</title> 23

Vzorové PHP: $xml = " <username>{$username}</username> <usertoken>{$token}</usertoken> <requesttype>campaigns</requesttype> <requestmethod>update</requestmethod> <id>80</id> <htmlbody>html</htmlbody> <textbody>text VERZE</textbody> <name>new NAME OF CAMPAIGN</name> <title>new SUBJECT</title> "; Pokud je vše v pořádku, vrátí se: <status> SUCCESS </status> 1 </data> 2.13 Statistika kampaní: Získat vrácené kontakty dle kampaně Pomocí této metody získáme všechny vrácené kontakty, které byly v rámci jedné kampaně označeny jako vrácené. K získání této informace musíme znát ID statistiky = ID rozesílky. Vzorové XML: <requesttype>newsletterstats</requesttype> 24

<requestmethod>getbounces</requestmethod> <id>133</id> Vzorové PHP: $xml = " <username>{$username}</username> <usertoken>{$token}</usertoken> <requesttype>newsletterstats</requesttype> <requestmethod>getbounces</requestmethod> <id>133</id> "; Pokud požadavek projde správně, dostaneme tento výpis: <status>success</status> <contact_id>32</contact_id> <type>1</type> <reason>emaildoesntexist</reason> <message>user unknown; rejecting</message> <time>2014 03 21 13:00:11</time> <emailaddress>test@rutvaclav.cz</emailaddress> </data> Důvody, proč je kontakt vrácený: kontakt neexistuje, má plnou schránku, server neexistuje a server odmítá naše zprávy. 25

Pokud narazíte na to, že nás někdo blokuje, neváhejte kontaktovat podporu na podpora@smartemailing.cz a zařídíme odblokování. 2.14 Statistika kampaní: Získat kontakty, které neotevřely danou kampaň Pomocí této metody získáme všechny kontakty v dané statistice, kteří neotevřely danou kampaň. Otevření se započítá pokud kontakt stáhne obrázky v kampani, nebo klikne na odkaz v kampani. K získání těchto informací je třeba mít k dispozici ID statistiky = ID rozesílky. Vzorové XML: <requesttype>newsletterstats</requesttype> <requestmethod>getunopened </requestmethod> <id>133</id> Vzorové PHP: $xml = " <username>{$username}</username> <usertoken>{$token}</usertoken> <requesttype>newsletterstats</requesttype> <requestmethod>getunopened </requestmethod> <id>133</id> "; Pokud request projde správně, získáme tento výpis: <status>success</status> 26

<id>16</id> <contact_id>4</contact_id> <newsletter_id>7</newsletter_id> <time>2014 02 24 21:13:05</time> <emailaddress>vaclav@smartemailing.cz</emailaddress> </data> 2.15 Statistika kampaní: Získat kontakty, které se z dané kampaně odhlásily Pomocí této metody získáme všechny kontakty v dané statistice, kteří se z dané rozesílky odhlásily. K získání těchto informací je třeba mít k dispozici ID statistiky = ID rozesílky. Vzorové XML: <requesttype>newsletterstats</requesttype> <requestmethod>getunsubscribes</requestmethod> <id>133</id> Vzorové PHP: $xml = " <username>{$username}</username> <usertoken>{$token}</usertoken> <requesttype>newsletterstats</requesttype> <requestmethod>getunsubscribes</requestmethod> <id>133</id> "; Pokud request projde v pořádku, získáme tyto data: 27

<status>success</status> <contact_id>3</contact_id> <contactlist_id>3</contactlist_id> <date>2014 02 24 21:14:10</date> <source>unsubscribe form (complete wipe)</source> <reason>abused</reason> <emailaddress>rut.vaclav@gmail.com</emailaddress> </data> <reason> Důvody odhlášení mohou být: Tyto emaily mě již nezajímají, (These emails are not interesting) Emaily mi chodí moc často, (tooften) Obtěžuje mě to a (abused) Jiné. (other) <source> Pokud máme více seznamů s veřejným názvem seznamu, budou zde vypsané seznamy, z kterých se kontakt odhlásil. 2.16 Statistika kampaní: Získat kontakty, které klikly na odkaz v dané kampani Pomocí této metody získáme všechny kontaky, které klikaly na odkazy v dané kamapni i s odkazy kliků. K získání této statistiky je třeba znát ID statistiky = ID rozesílky. Vzorové XML: <requesttype>newsletterstats</requesttype> <requestmethod>getclicks</requestmethod> <id>133</id> Vzorové PHP: equire '../base.php'; $xml = " 28

<username>{$username}</username> <usertoken>{$token}</usertoken> <requesttype>newsletterstats</requesttype> <requestmethod>getclicks</requestmethod> <id>133</id> "; Pokud request projde v pořádku, dostaneme tento výpis: <status>success</status> <contact_id>4</contact_id> <time>2014 02 20 11:23:40</time> <emailaddress>vaclav@smartemailing.cz</emailaddress> <href>http://rutvaclav.cz</href> </data> 2.17 Statistika kampaní: Získat kontakty, které otevřely danou kampaň Touto metodou získáme všechny kontakty, které mají příznak, že danou kampaň otevřely. Tento příznak získá kontakt pokud klikl na nějaký odkaz nebo si stáhl obrázky z kampaně. K získání této statistiky je třeba znát její ID = ID rozesílky. Vzorové XML: <requesttype>newsletterstats</requesttype> <requestmethod>getopens</requestmethod> <id>dopln_id_rozesilky</id> Vzorové PHP: 29

$xml = " <username>{$username}</username> <usertoken>{$token}</usertoken> <requesttype>newsletterstats</requesttype> <requestmethod>getopens</requestmethod> <id>132</id> "; Pokud request projde v pořádku, dostaneme tyto informace: <status>success</status> <contact_id>4</contact_id> <agent>mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/32.0.1700.107 Safari/537.36</agent> <time>2014 02 20 11:23:40</time> <emailaddress>vaclav@smartemailing.cz</emailaddress> </data> Zde kromě adresy klienta, který si kampaň otevřel (<emailaddress>)máme k dispozici další informace jako je Operační systém, Prohlížeč (<agent>) a čas otevření v <time>. 2.18 Statistika kampaní: Získat přehled pro celou kampaň Touto metodou získáme kompletní přehled informací o rozesílce. K získání těchto informací je zapotřebí znát ID statistiky = ID rozesílky. Vzorové XML: <requesttype>newsletterstats</requesttype> <requestmethod>getsummary</requestmethod> 30

<id>dopln_id_rozesilky</id> Vzorové PHP: $xml = " <username>{$username}</username> <usertoken>{$token}</usertoken> <requesttype>newsletterstats</requesttype> <requestmethod>getsummary</requestmethod> <id>132</id> "; Pokud request projde v pořádku, dostaneme tyto informace o rozesílce: <status>success</status> <start>2014 02 20 11:16:05</start> <finished>2014 02 20 11:16:05</finished> <campaign_id>7</campaign_id> <sendername>václav Růt</sendername> <senderemail>rut.v@seznam.cz</senderemail> <replyto>rut.v@seznam.cz</replyto> <track>{"utm_source":"newsletter","utm_medium":"email","utm_name":"ca mpaign_7","utm_campaign":"campaign_7"}</track> <summary> <sent>1</sent> <opened>1</opened> <openedtotal>1</openedtotal> <clicked>1</clicked> <unsubscribed>0</unsubscribed> <bounced>0</bounced> <unopened>0</unopened> </summary> </data> 31

Z tohoto výpisu můžeme získat tyto informace: <statust> zda rozesílka proběhla v pořádku <start> kdy začala rozesílka, <finished> kdy byla rozesílka dokončena, <campaign_id> id kampaně, který byla rozeslána, <sendername> jméno odesílatele pro tuto rozesílku, <sendermail> adresa odesílatele pro tuto rozesílku, <replyto> email pro odpovědi pro tuto rozesílku, <track> informace pro google analytics, <sent> počet adres, na které byla rozesílka provedena, <opened> počet unikátních otevření, <openedtotal> počet otevření celkem, <clicked> počet kliknutí, <unsubscribed> počet odhlášených, <bounced> počet vrácených, <unopened> počet neotevřených. 2.19 Statistika SmartKampaně: Získat odhlášené kontakty dle SmartKampaně Pomocí této metody získáme všechny odhlášené kontakty, které se odhlásily v rámci SmartKampaně s námi zvoleným ID. K získání této statistiky musíme znát ID SmartKampaně. Vzorové XML: <requesttype>autoresponderstats</requesttype> <requestmethod>getunsubscribes</requestmethod> <id>dopln_id_sk</id> Vzorové PHP: $xml = " <username>{$username}</username> <usertoken>{$token}</usertoken> <requesttype>autoresponderstats</requesttype> <requestmethod>getunsubscribes</requestmethod> 32

<id>12</id> "; Pokud request projde v pořádku, získáme tyto informace: <status>success</status> <contact_id>4</contact_id> <contactlist_id>5</contactlist_id> <date>2014 03 24 14:58:41</date> <source>unsubscribe form (complete wipe)</source> <reason /> <emailaddress>vaclav@smartemailing.cz</emailaddress> </data> 2.20 Statistika SmartKampaně: Získat kontakty, které neotevřely danou SmartKampaň Pomocí této metody získáme všechny kontakty v dané statistice, kteří neotevřely danou SmartKampaň. Otevření se započítá pokud kontakt stáhne obrázky v kampani, nebo klikne na odkaz ve SmartKampani. K získání těchto informací je třeba mít k dispozici ID SmartKampaně. Vzorové XML: <requesttype>autoresponderstats</requesttype> <requestmethod>getunopened</requestmethod> <id>id_smartkampane</id> Vzorové PHP: 33

$xml = " <username>{$username}</username> <usertoken>{$token}</usertoken> <requesttype>autoresponderstats</requesttype> <requestmethod>getunopened</requestmethod> <id>12</id> "; Pokud request projde v pořádku, získáme tyto informace: <status>success</status> <id>4</id> <contact_contactlist_id>8</contact_contactlist_id> <contact_id>3</contact_id> <autoresponder_id>3</autoresponder_id> <time>2014 03 24 15:34:07</time> <emailaddress>rut.vaclav@gmail.com</emailaddress> </data> 2.21 Statistika SmartKampaně: Získat kontakty, které otevřely danou SmartKampaň Touto metodou získáme všechny kontakty, které mají příznak, že danou SmartKampaň otevřely. Tento příznak získá kontakt pokud klikl na nějaký odkaz nebo si stáhl obrázky z SmartKampaně. K získání této statistiky je třeba znát její ID. Vzorové XML: <requesttype>autoresponderstats</requesttype> <requestmethod>getopens</requestmethod> 34

<id>id_smartkampane</id> Vzorové PHP: $xml = " <username>{$username}</username> <usertoken>{$token}</usertoken> <requesttype>autoresponderstats</requesttype> <requestmethod>getopens</requestmethod> <id>12</id> "; Pokud request projde v pořádku, získáme tyto informace: <status>success</status> <autoresponder_id>3</autoresponder_id> <contact_id>4</contact_id> <agent>mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_2) AppleWebKit/537.74.9 (KHTML, like Gecko)</agent> <time>2014 03 24 14:58:03</time> <emailaddress>vaclav@smartemailing.cz</emailaddress> </data> 2.22 Statistika SmartKampaně: Získat kontakty, které klikly na odkaz v dané SmartKampani Pomocí této metody získáme všechny kontaky, které klikaly na odkazy v dané SmartKamapni i s odkazy kliků. K získání této statistiky je třeba znát ID SmartKampaně. Vzorové XML: 35

<requesttype>autoresponderstats</requesttype> <requestmethod>getclicks</requestmethod> <id>id_smartkampane</id> Vzorové PHP: $xml = " <username>{$username}</username> <usertoken>{$token}</usertoken> <requesttype>autoresponderstats</requesttype> <requestmethod>getclicks</requestmethod> <id>12</id> "; Pokud request projde v pořádku, získáme tyto informace: <status>success</status> <contact_id>4</contact_id> <autoresponder_id>3</autoresponder_id> <time>2014 03 24 15:53:52</time> <emailaddress>vaclav@smartemailing.cz</emailaddress> <href>http://www.smartemailing.cz</href> </data> 36

2.23 Statistika SmartKampaní: Získat vrácené kontakty dle SmartKampaně Pomocí této metody získáme všechny vrácené kontakty, které byly v rámci jedné SmartKampaně označený jako vrácené. K získání této informace musíme znát ID SmartKampaně. Vzorové XML: <requesttype>autoresponderstats</requesttype> <requestmethod>getbounces</requestmethod> <id>id_smartkampane</id> Vzorové PHP: $xml = " <username>{$username}</username> <usertoken>{$token}</usertoken> <requesttype>autoresponderstats</requesttype> <requestmethod>getbounces</requestmethod> <id>12</id> "; Pokud request projde v pořádku, získáme tyto informace: <status>success</status> <contact_id>36</contact_id> <type>1</type> <reason>relayerror</reason> <message>message could not be delivered</message> <time>2014 03 24 16:05:11</time> 37

<emailaddress>nesm@ysl.com</emailaddress> </data> 2.24 Statistika SmartKampaně: Získat přehled pro celou SmartKampaň Touto metodou získáme kompletní přehled informací o rozesílce SmartKampaně. K získání těchto informací je zapotřebí znát ID SmartKampaně. Vzorové XML: <requesttype>autoresponderstats</requesttype> <requestmethod>getsummary</requestmethod> <id>id_smartkampane</id> Vzorové PHP: $xml = " <username>{$username}</username> <usertoken>{$token}</usertoken> <requesttype>autoresponderstats</requesttype> <requestmethod>getsummary</requestmethod> <id>12</id> "; Pokud request projde v pořádku, dostaneme tyto informace o rozesílce: <status>success</status> 38

<campaign_id>10</campaign_id> <sendername>václav Růt</sendername> <senderemail>rut.v@seznam.cz</senderemail> <replyto>rut.v@seznam.cz</replyto> <track /> <summary> <sent>3</sent> <opened>1</opened> <openedtotal>1</openedtotal> <clicked>1</clicked> <unsubscribed>1</unsubscribed> <bounced>1</bounced> <unopened>1</unopened> </summary> </data> Z tohoto výpisu můžeme získat tyto informace: <statust> zda rozesílka proběhla v pořádku <campaign_id> id kampaně, který byla rozeslána, <sendername> jméno odesílatele pro tuto rozesílku, <sendermail> adresa odesílatele pro tuto rozesílku, <replyto> email pro odpovědi pro tuto rozesílku, <track> informace pro google analytics, <sent> počet adres, na které byla rozesílka provedena, <opened> počet unikátních otevření, <openedtotal> počet otevření celkem, <clicked> počet kliknutí, <unsubscribed> počet odhlášených, <bounced> počet vrácených, <unopened> počet neotevřených. 2.25 Kontakt: Získat všechny kontakty Touto metodou získáme všechny kontakty, které jsou pod účtem. Pro získání musíme mít platný API token a aktivní API. Vzorové XML: 39

<requesttype>contacts</requesttype> <requestmethod>getall</requestmethod> Vzorové PHP: $xml = ' <username>'.$username.'</username> <usertoken>'.$token.'</usertoken> <requesttype>contacts</requesttype> <requestmethod>getall</requestmethod> '; Pokud request projde bez problému, získáme tyto informace: <status>success</status> <language>cs_cz</language> <created>2014 02 06 17:04:22</created> <updated>2014 03 24 19:10:22</updated> <blacklisted>0</blacklisted> <emailaddress>vaclav@smartemailing.cz</emailaddress> <domain>smartemailing.cz</domain> <name>václav</name> <surname>růt</surname> <titlesbefore>bc.</titlesbefore> <titlesafter /> <birthday>2014 03 24 00:00:00</birthday> <nameday>2014 03 26 00:00:00</nameday> <salution>václave</salution> <company>smartemailing</company> <street>ulice</street> <town>město</town> <country>země</country> 40

<postalcode>39900</postalcode> <notes /> <phone>666777888</phone> <cellphone /> <softbounced>0</softbounced> <hardbounced>0</hardbounced> <id>4</id> <customfields> <id>1</id> <value>affilbox kód</value> <id>3</id> <value>2013 02 06 00:00:00</value> <id>4</id> <value> 1 </value> </customfields> <contactliststatuses> <id>5</id> <status>unsubscribed</status> </contactliststatuses> </data> 2.24 Kontakt: Získat jeden kontakt Touto metodou získáme jeden určitý kontakt, který je pod účtem. Pro získání potřebujeme znát jeho ID nebo e mail. Vzorové XML: <requesttype>contacts</requesttype> 41

<requestmethod>getone</requestmethod> <id>insert_contacts_id</id> <! OR <emailaddress>martin@smartemailing.cz</emailaddress> > Vzorové PHP: $xml = ' <username>'.$username.'</username> <usertoken>'.$token.'</usertoken> <requesttype>contacts</requesttype> <requestmethod>getone</requestmethod> <id>25237</id> <! OR <emailaddress>martin@smartemailing.cz</emailaddress> > '; Pokud request projde v pořádku, získáme stejný výpis informací jako v případě getall, 2.25 2.25 Kontakt: Vytvořit, update kontakt Touto metodou můžeme vytvořit nebo updatovat kontakt v aplikaci. Pro založení kontaktu je povinné vyplnit e mailovou adresu, další pole jsou volitelná. Pouze pole obsažená v XML jsou aktualizovaná, ostatní zůstávají beze změny. Vzor XML: <requesttype>contacts</requesttype> <requestmethod>createupdate</requestmethod> <! only emailaddress is required only fields contained in XML are updated > 42

<emailaddress>martin@smartemailing.cz</emailaddress> <language>cs_cz</language> <! cs_cz sk_sk en_gb > <blacklisted>0</blacklisted> <name>martin</name> <surname>strouhal</surname> <titlesbefore>ing.</titlesbefore> <titlesafter>csc.</titlesafter> <birthday>2013 01 01</birthday> <nameday>2013 11 11</nameday> <! year does not matter > <salution></salution> <! will be generated if this field is empty > <company>my Corp</company> <street>long 123</street> <town>my Town</town> <country>czech Republic</country> <postalcode>123456</postalcode> <notes>something very long</notes> <phone>+420123456789</phone> <cellphone>+420123456789</cellphone> <softbounced>0</softbounced> <! number of 'soft' bounces > <hardbounced>0</hardbounced> <! 1 if contact is hardbounced > <customfields> <id>43</id> <value> 25 </value> </customfields> <contactliststatuses> <! statuses in lists not contained in this xml will be untouched if any if items is not valid (bad id or status) it is ignored without throwing an error > <id>21</id> 43

<status>banned</status> <! unconfirmed confirmed unsubscribed banned removed > <id>3</id> <status>removed</status> </contactliststatuses> Při vytváření kontaktu je v XML část <contactliststatuses> která se stará o to, do kterého seznamu je kontakt ukládán a s jakým stavem. Každé vlastní pole má dle typu jiný zápis!! Nejdříve si vytvořte vlastní pole, vypište si kontakt a dle něj vytvořte XML zápis. Vzor PHP: $xml = " <username>{$username}</username> <usertoken>{$token}</usertoken> <requesttype>contacts</requesttype> <requestmethod>createupdate</requestmethod> <! only emailaddress is required only fields contained in XML are updated > <emailaddress>martin@smartemailing.cz</emailaddress> <language>cs_cz</language> <! cs_cz sk_sk en_gb > <blacklisted>0</blacklisted> <name>martin</name> <surname>strouhal</surname> <titlesbefore>ing.</titlesbefore> <titlesafter>csc.</titlesafter> <birthday>2013 01 01</birthday> <nameday>2013 11 11</nameday> <! year does not matter > <salution></salution> <! will be generated if this field is empty > 44

<company>my Corp</company> <street>long 123</street> <town>my Town</town> <country>czech Republic</country> <postalcode>123456</postalcode> <notes>something very long</notes> <phone>+420123456789</phone> <cellphone>+420123456789</cellphone> <softbounced>0</softbounced> <! number of 'soft' bounces > <hardbounced>0</hardbounced> <! 1 if contact is hardbounced > <customfields> <id>43</id> <value> 25 </value> </customfields> <contactliststatuses> <! statuses in lists not contained in this xml will be untouched if any if items is not valid (bad id or status) it is ignored without throwing an error > <id>21</id> <status>banned</status> <! unconfirmed confirmed unsubscribed banned removed > <id>3</id> <status>removed</status> </contactliststatuses> "; 45

Vysvětlení položek: <emailaddress> emailová adresa <language>cs_cz</language> jazyk kontaktu, podporované tvary: <! cs_cz sk_sk en_gb > <blacklisted> 1, pokud je kontakt na blacklistu (nebude nikdy nic doručeno) <name> křestní jméno <surname> příjemní <titlesbefore> titul před jménem <titlesafter> titul za jménem <birthday> narozeniny ve formátu:2013 01 01 <nameday> svátek ve formátu: 2013 11 11 (rok nehraje roli) <salution> oslovení, pokud nebude vyplněno, doplní se dle křestního jména, pokud to prázdné, i oslovení bude prázdné <company> společnost <street> ulice <town> město <country> stát <postalcode> směrovací číslo <notes> poznámka <phone> telefon <cellphone> mobilní telefon <softbounced> počet softbounces <hardbounced> pokud 1, hardbounce (nebude nic doručeno) Pokud je kontakt úspěšně vytvořen, dostaneme tuto informaci: <status>success</status> 1</data> 2.26 Kontakt: Smazat kontakt Touto metodou můžeme smazat určitý kontakt. Ke smazání potřebujeme znát ID kontaktu nebo jeho e mailovou adresu. Vzorové XML: <requesttype>contacts</requesttype> <requestmethod>delete</requestmethod> 46

<id>23970</id> <! OR <emailaddress>vaclav@smartemailing.cz</emailaddress> > Vzorové PHP: $xml = ' <username>'.$username.'</username> <usertoken>'.$token.'</usertoken> <requesttype>contacts</requesttype> <requestmethod>delete</requestmethod> <id>23970</id> <! OR <emailaddress>martin@smartemailing.cz</emailaddress> > '; Pokud je kontakt úspěšně smazán, získáme tuto informaci: <status>success</status> 1</data> Pokud kontakt neexistuje: <status>failed</status> <errormessage>contact does not exist</errormessage> 2.27 Kontakt: Získat všechny odhlášené kontakty Touto metodou získáme všechny kontakty, které v jakémkoliv seznamu mají stav odhlášený. K získání těchto informací je zapotřebí znát API údaje k účtu. Vzor XML: 47

<requesttype>contacts</requesttype> <requestmethod>getallunsubscribed</requestmethod> Pokud request projde v pořádku, získáme tyto informace: <status>success</status> <language>cs_cz</language> <created>2014 04 11 08:49:08</created> <updated>2014 04 11 08:49:19</updated> <blacklisted>0</blacklisted> <emailaddress>vaclav@smartemailing.cz</emailaddress> <domain>smartemailing.cz</domain> <name>václav Růt</name> <surname /> <titlesbefore /> <titlesafter /> <birthday /> <nameday /> <salution>václave</salution> <company /> <street /> <town /> <country /> <postalcode /> <notes /> <phone /> <cellphone /> <softbounced>0</softbounced> <hardbounced>0</hardbounced> <id>353</id> <customfields /> <contactliststatuses> <id>20</id> 48

<status>unsubscribed</status> </contactliststatuses> </data> Nejdůležitější je zde pro nás část: <contactliststatuses> Která vypisuje seznamy kontaktů a stav kontaktu v těchto seznamech. 2.28 Seznamy kontaktů: Získat kontakty dle seznamu kontaktů Tato metoda vrací kontakty dle ID seznamu. K získání tohoto výpisu je třeba znát ID seznamu kontaktů a mít platný username a token. Vzorové XML: <usertoken>usertoken</usertoken> <requesttype>contactlists</requesttype> <requestmethod>getcontacts</requestmethod> <id>id_list</id> Vozorové PHP: $xml = " <username>{$username}</username> <usertoken>{$token}</usertoken> <requesttype>contactlists</requesttype> <requestmethod>getcontacts</requestmethod> <id>id_list</id> "; Pokud request projde v pořádku, dostaneme tento výpis: 49

<status>success</status> <contact_id>354</contact_id> <status>confirmed</status> <updated /> <added>2014 04 14 12:13:54</added> <emailaddress>vaclav@smartemailing.cz</emailaddress> 50