====== Rozesilam.cz API dokumentace ======



===== Informace před použitím API =====

  * Před použitím API se přihlašte do administrace svého účtu. \\
  * V nastavení (horní menu) naleznete záložku **API a Sessions**.\\
  * Pokud chcete používat PHP API, je pro Vás důležité **Příchozí SessionID**
  * Doporučujeme nastavit omezení na IP adresu vašeho PHP serveru pro zvýšení bezpečnosti.
  * Stáhněte si [[start|API class výše]]. Rozbalte a prozkoumejte. Třída je poměrně dokumentovaná přímo v souboru. Pokud používáte vlastní instalaci Rozesilam.cz na svém serveru, je třeba upravit následující URL:
<code php>protected $MM_apiURL = "http://www.rozesilam.cz/API_connect.php";</code>
  * Třídu nahrajete tam kam potřebujete a využijete např. dle příkladů níže

**Upozornění:** Pokud byste chtěli dávat vadná (nebo škodná) data, skript na straně Rozesilam.cz data kontroluje a každý pokus přes api se loguje

===== Changelog =====

<code>
2017-11-19 - 2018-11-19
* velké změny
</code>

===== Příklady použití PHP API =====

Pomocí API můžete kontrolovat spoustu věcí, zde jsou příklady užití

==== Vzdálené přihlášení ====

Tato funkce vám vrátí řetězec pomocí kterého se můžete přihlásit do administrace. Toto přihlášení je platné pouze pro daný den, poté přihlašovací token vyprší. Toto slouží dobře, pokud chcete do své administrace zahrnout iframe s konkrétní stránkou na Rozesilam.cz. Neboť Rozesilam.cz pozná, že je volán z iframu, skryje horní menu a uživatel nemusí poznat, že pracuje v iframu. 


<file php loginMe.php>
<?php 
include('API_class.php');

$apiCall = new MassMailingAPI();
$apiCall->setSessionID("Vaše Příchozí SessionID");
$hash = $apiCall->LoginGetHash("vas@email.cz");
$report = $apiCall->SendRequest();

	echo '<iframe src="http://www.rozesilam.cz/admin/mailingy/?'.$hash.'" id="iframe1" width="100%" height="1800" border="0" style="border: 0px"></iframe>';
 ?>
</file>



==== Statistiky ====

=== Získání měsíčních statistik ===

Vrátí pole (array) aktivních (nesmazaných) mailingů.


<file php listStats.php>
<?php 
include('API_class.php');

$apiCall = new MassMailingAPI();
$apiCall->setSessionID("Vaše Příchozí SessionID");
$apiCall->StatsMesicniGet();
$report = $apiCall->SendRequest();
if (!$report)
{
	echo $apiCall->getError();
}else {

if ($report["action"] == "statsmesicni" && $report["MMpocet"]>0 && isset($report["array"]["stats"])) 
{
	foreach ($report["array"]["stats"] as $k => $v) 
	{
		echo  $v["date"]; echo ";";
		echo  (int)$v["mailingu"]; echo ";";
		echo  (int)$v["vraceno"]; echo ";";
		echo  (int)$v["doruceno"]; echo ";";
		echo  (int)$v["pocet_emailu"]; echo ";";
		echo  (int)$v["kliknuti"]; echo ";";
		echo  (int)$v["otevreno"]; echo ";";
		echo  (int)$v["odhlaseno"]; echo ";";
		echo  (int)$v["delivery_rate"]; echo ";";
		echo  (int)$v["odhlaseno_rate"]; echo ";";
		echo  (int)$v["click_rate"]; echo ";";
		echo  (int)$v["open_rate"]; echo ";";
		echo  (int)$v["open_per_mailing"]; echo ";";
		echo  (int)$v["click_per_mailing"]; echo ";";
		echo  (int)$v["odhlaseno_per_mailing"]; echo ";";
		
	}
	
	} else {
	
	echo "Pravděpodobně jste ještě neodeslal žádnou emailovou kampaň, nemáte tedy k dispozici statistiky.";

	}

} ?>
</file>


==== Uživatele ====


=== Editace a přidání uživatele ===

Tato položka se pokusí editovat uživatele, pokud uživatel neexistuje, vytvoří jej, pokud má uživatel příznak smazání, maže jej.
<code>
UserEdit($email,$data = array(),$skupiny = false,$odhlasit=false,$smazat=false,$odhlasit_ze_vsech_skupin=false)
@param string (email) - unique identifier - $email
	 * @param array of the additional data $data
	 * $data =
	 *	stav  (0 = aktivní, -1 = smazaný, -2 = odhlášený)
	 *	info  (string)
	 *	jmeno  (string(250))
	 *	prijmeni (string(250))
	 *	pohlavi  ("","m","z")
	 *	osloveni (string(250))
	 *	adresa   (string)
	 *	rok_narozeni (int(4))
	 *
	 *	další pole jsou mohou být vaše vlastní, jejich aliasy viz nastavení - API
	 * 	nelze posílat obrázky a soubory
	 *
	 *	pokud byste chtěli dávat vadná data, skript na straně Rozesilam.cz data kontroluje a každý pokus přes api se loguje
	 * @param array nebo integer skupiny do které odběratel patří $skupiny
	 * @param bool $smazat
</code>
Jednoduché přidání/editace nového uživatele
<file php UserEdit.php>
<?php 
include('API_class.php');

$apiCall = new MassMailingAPI();
$apiCall->setSessionID("Vaše Příchozí SessionID");
$apiCall->UserEdit("test@test.cz",array("jmeno"=>"David","prijmeni"=>"Marek","pohlavi"=>"m","rok_narozeni"=>1999),99);
$report = $apiCall->SendRequest();
if (!$report)
{
	echo $apiCall->getError();
}else {
	echo "Akce proběhla v pořádku";
} ?>
</file>


=== Odhlášení uživatele ===

Tento příklad u uživatele nastaví status, že je odhlášení - napojení na skupiny zůstává, ale uživatel díky příznaku nedostává ŽÁDNÝ email \\
//Obalovač funkce UserEdit - odhlašuje uživatele z odběru - nastaví se u něj příznak -2, což znamená, že je uživatel odhlášený a ŽÁDNÝ email, ať je třeba ve více skupinách, mu nepříjde!//

<file php odhlaseniOdberatel.php>
<?php 
include('API_class.php');

$apiCall = new MassMailingAPI();
$apiCall->setSessionID("Vaše Příchozí SessionID");
$apiCall->UserOdhlasit("odhlasit@test.cz");
$report = $apiCall->SendRequest();
if (!$report)
{
	echo $apiCall->getError();
}else {
	echo "Akce proběhla v pořádku";
} ?>
</file>

=== Smazání uživatele ===

Smaže uživatele  \\
//Obalovač funkce UserEdit - maže uživatele - ne v pravém slova smyslu, nastavuje příznak -1 u uživatele, uživatel je stále v databázi//

<file php smazaniOdberatel.php>
<?php 
include('API_class.php');

$apiCall = new MassMailingAPI();
$apiCall->setSessionID("Vaše Příchozí SessionID");
$apiCall->UserSmazat("odhlasit@test.cz");
$report = $apiCall->SendRequest();
if (!$report)
{
	echo $apiCall->getError();
}else {
	echo "Akce proběhla v pořádku";
} ?>
</file>

=== Obnovení uživatele ===

Pokud jste použili funkce UserSmazat nebo UserOdhlasit přes API (nebo nastaví příznaky přes administraci), tak tato funkce jej vrátí k životu   \\
//Obalovač funkce UserEdit - obnovuje uživatele - pokud byl uživatel smazaný nebo odhlášený, nastavuje u něj stav = 0 tedy aktivní uživatel pro příjem zpráv (pokud je zařazen ve skupině)//

<file php obnovOdberatel.php>
<?php 
include('API_class.php');

$apiCall = new MassMailingAPI();
$apiCall->setSessionID("Vaše Příchozí SessionID");
$apiCall->UserObnov("odhlasit@test.cz");
$report = $apiCall->SendRequest();
if (!$report)
{
	echo $apiCall->getError();
}else {
	echo "Akce proběhla v pořádku";
} ?>
</file>


==== Skupiny ====


=== Výpis skupin ===

Vrátí seznam všech skupin. S příznakem i smazané.


<file php listSkupin.php>
<?php 
include('API_class.php');

$apiCall = new MassMailingAPI();
$apiCall->setSessionID("Vaše Příchozí SessionID");
$apiCall->SkupinaList(true); //true protože chceme i smazané
$report = $apiCall->SendRequest();
if (!$report)
{
	echo $apiCall->getError();
}else {

if ($report["action"] == "skupinylist" && $report["MMpocetSkupin"]>0 && isset($report["array"]["skupina"])) 
{
	foreach ($report["array"]["skupina"] as $k => $v) 
	{
		echo (int)$v["id"].";";
	
		echo $v["name"].";";
		echo $v["info"].";";
	}
	
	} else {
	
	echo "Pravděpodobně nemáte založenou žádnou skupinu, založte jí.";

	}

} ?>
</file>


=== Editace a přidání skupiny ===

Tato položka se edituje skupiny nebo přidává. Pro přidání lze použít zjednodušený obalovač funkce SkupinaAdd, kterému chybí první parametr - identifikátor skupiny a stav.

<code>
SkupinaEdit($id_skupiny nebo $string_nazev,$novynazev,$noveinfo,$stav=false =nemění se,-1 = smazaný, 0 = aktivní);

SkupinaAdd($nazev,$info);
</code>

Jednoduché přidání/editace nové skupiny
<file php SkupinaEdit.php>
<?php 
include('API_class.php');

$apiCall = new MassMailingAPI();
$apiCall->setSessionID("Vaše Příchozí SessionID");
$apiCall->SkupinaEdit(99,"Novy název skupiny","Nové info skupiny");
$report = $apiCall->SendRequest();
if (!$report)
{
	echo $apiCall->getError();
}else {
	echo "Akce proběhla v pořádku";
} ?>
</file>


=== Smazání skupiny ===

Smaže skupinu\\
//Obalovač funkce SkupinaEdit - maže skupinu - ne v pravém slova smyslu, nastavuje příznak -1, skupina je stále v databázi//

Pro id skupiny je možné použít její název jako string, skupina bude dohledána dle názvu.

<file php smazaniSkupina.php>
<?php 
include('API_class.php');

$apiCall = new MassMailingAPI();
$apiCall->setSessionID("Vaše Příchozí SessionID");
$apiCall->SkupinaSmazat(99);
$report = $apiCall->SendRequest();
if (!$report)
{
	echo $apiCall->getError();
}else {
	echo "Akce proběhla v pořádku";
} ?>
</file>


=== Obnovení skupiny ===

Pokud jste použili funkci SkupinaSmazat přes API (nebo smazali přes administraci), tak tato funkce jej vrátí k životu   \\
//Obalovač funkce SkupinaEdit - obnovuje skupinu - pokud byla smazana, nastavuje u ní stav = 0 tedy aktivní //

<file php obnovSkupina.php>
<?php 
include('API_class.php');

$apiCall = new MassMailingAPI();
$apiCall->setSessionID("Vaše Příchozí SessionID");
$apiCall->SkupinaObnov(99);
$report = $apiCall->SendRequest();
if (!$report)
{
	echo $apiCall->getError();
}else {
	echo "Akce proběhla v pořádku";
} ?>
</file>

=== Aktuální počet aktivních odběratelů ve skupině ===

 Zjistí počet aktivních odběratelů u skupiny - povinný parametr ID vaší skupiny.

<file php SkupinaPocetOdberatelu.php>
<?php 
include('API_class.php');

$apiCall = new MassMailingAPI();
$apiCall->setSessionID("Vaše Příchozí SessionID");
$apiCall->SkupinaPocetOdberatelu((int)99);
$report = $apiCall->SendRequest();
if (!$report)
{
	echo $apiCall->getError();
}else {
	echo $report["pocet_odberatelu"]." odběratelů";
} ?>
</file>


==== Mailingy ====

=== Odeslání testu ===

Odešle testovací zprávu pro mailing na daný email. ID mailingu můžete získat např. z MailingList();

<file php odesliTest.php>
<?php 
include('API_class.php');

$apiCall = new MassMailingAPI();
$apiCall->setSessionID("Vaše Příchozí SessionID");
$apiCall->MailingTestSend((int)99,"test@test.cz");
$report = $apiCall->SendRequest();
if (!$report)
{
	echo $apiCall->getError();
}else {
	echo "Akce proběhla v pořádku";
} ?>
</file>


=== Odeslání mailingu ===

Označit mailing k odeslání aneb **odešle mailing** a uzamkne jej proti úpravám. ID mailingu můžete získat např. z MailingList();

<file php odesliTest.php>
<?php 
include('API_class.php');

$apiCall = new MassMailingAPI();
$apiCall->setSessionID("Vaše Příchozí SessionID");
$apiCall->MailingSend((int)99);
$report = $apiCall->SendRequest();
if (!$report)
{
	echo $apiCall->getError();
}else {
	echo "Akce proběhla v pořádku";
} ?>
</file>

=== Získání seznamu mailingů ===

Vrátí pole (array) aktivních (nesmazaných) mailingů.


<file php listMailing.php>
<?php 
include('API_class.php');

$apiCall = new MassMailingAPI();
$apiCall->setSessionID("Vaše Příchozí SessionID");
$apiCall->MailingList();
$report = $apiCall->SendRequest();
if (!$report)
{
	echo $apiCall->getError();
}else {

if ($report["action"] == "mailinglist" && $report["MMpocetKampani"]>0 && isset($report["array"]["mailing"])) 
{
	foreach ($report["array"]["mailing"] as $k => $v) 
	{
		echo (int)$v["id"].";";
		
		if ($v["status"] == 0)
			echo "<strong>k odeslání</strong>";
		elseif ($v["status"] == 3)
			echo "odeslán, statistiky";
		elseif ($v["status"] == 1)
			echo "zpracovává se";
		elseif ($v["status"] == 2)
			echo "ve frontě (odesílá se)";
		else
			echo "-";
			
		echo $v["predmet"].";";
		echo $v["textinfo"].";";
		echo $v["date_add"].";";
	}
	
	} else {
	
	echo "Pravděpodobně nemáte založenou žádnou emailovou kampaň, založte jí.";

	}

} ?>
</file>


=== Smazání Mailingu ===

Smaže mailing se zadaným ID; (Nastaví příznak smazání, zůstává stále v DB);

<file php smazMailing.php>
<?php 
include('API_class.php');

$apiCall = new MassMailingAPI();
$apiCall->setSessionID("Vaše Příchozí SessionID");
$apiCall->MailingDelete((int)99);
$report = $apiCall->SendRequest();
if (!$report)
{	echo $apiCall->getError();	}else {	echo "Akce proběhla v pořádku";	} 
?>
</file>

=== Informace o Mailingu ===

Můžete získat informace o mailingu; Vrací tyto pole o mailingu:\\
  * MMmailingid
  * predmet
  * odeslat_start (v kolik zahájit odeslání - uživatelem nastavené)
  * emailto_before
  * emailto_after 
  * mailing_info (dodatečné informace)
  * date_started (reálně odesílání začalo v)
  * date_ended (reálně odesílání skončilo v)
  * pocet_emailu (počet emailu)
  * click (počet kliků na odkazy v tomto mailingu)
  * vracenych (počet vrácených emailů)
  * From
  * FromName
  * ReplyTo
  * ReplyToName 
  * linkWebVersion (0/1 odkaz na webovou verzi)
  * cteno (kolik lidí četlo)
  * odhlaseno (kolik lidí se odhlásilo přes odkaz v tomto mailingu)

<file php MailingGet.php>
<?php 
include('API_class.php');

$apiCall = new MassMailingAPI();
$apiCall->setSessionID("Vaše Příchozí SessionID");
$apiCall->MailingGet((int)99);
$report = $apiCall->SendRequest();
if (!$report)
{	
	echo $apiCall->getError();	
}else {	
	print_r($report); 
	echo "Akce proběhla v pořádku";	
} 
?>
</file>

=== Odkaz na náhled Mailingu ===

Získá URL pro zobrazení mailingu - vhodné jako iframe po odeslání mailingu do statistik.
Adresa, která se vrátí ($return["link"]), je needitovatelný obsah jen pro náhled, pro editovatelný obsah je jiný příklad. 

<file php MailingGetContentLink.php>
<?php 
include('API_class.php');

$apiCall = new MassMailingAPI();
$apiCall->setSessionID("Vaše Příchozí SessionID");
$apiCall->MailingGetContentLink((int)99);
$report = $apiCall->SendRequest();
if (!$report)
{	
	echo $apiCall->getError();	
}else {	
	echo '<iframe src="'.$report["link"].'" width="100%" height="800"></iframe>';	
} 
?>
</file>


=== Odkaz na editaci obsahu Mailingu ===

Získá URL pro zobrazení a **EDITACI** mailingu.
Adresa, která se vrátí ($return["link"]), je editovatelný obsah. Pokud již mailing nelze editovat, vrací chybu č.13, doporučujeme tedy při chybě získat náhledovou adresu.

<file php MailingGetEditContentLink.php>
<?php 
include('API_class.php');

$apiCall = new MassMailingAPI();
$apiCall->setSessionID("Vaše Příchozí SessionID");
$apiCall->MailingGetEditContentLink((int)99);
$report = $apiCall->SendRequest();
if (!$report)
{	
	$apiCall->MailingGetContentLink((int)99);
	$report = $apiCall->SendRequest();
	if (!$report)
	{
		echo $apiCall->getError();
	}else{
		echo '<iframe src="'.$report["link"].'" width="100%" height="800"></iframe>';
	}
}else {	
	echo '<iframe src="'.$report["link"].'" width="100%" height="800"></iframe>';	
} 
?>
</file>

=== Editace stávajícího mailingu ===

Editace existujícího mailingu - možno měnit předmět atp. Pro založení mailingu stačí "false" u prvního parametru - Pro příklad přidání nového mailingu je přímo sekce níže. Zde je jen příklad editace \\
//array dat = "predmet"=>$predmet,"sablona"=>$sablona,"skupiny"=>$skupiny,"embedLocalImages"=>$embedLocalImages
//

<file php MailingEdit.php>
<?php 
include('API_class.php');

$apiCall = new MassMailingAPI();
$apiCall->setSessionID("Vaše Příchozí SessionID");
$apiCall->MailingEdit(99,
	array(
		"predmet"=>"Předmět zprávy eddd", //pro změnu předmětu
 		"skupiny"=>array(23,21), //ID skupin, které dostanou mailing - array nebo samostatný integer. Pokud chybí skupiny v editaci, tak se nebudou měnit! 
		"From"=>"mailing@xxx.cz", //nepovinné, pokud chybí, předvyplní se z vašeho nastavení 
		"FromName"=>"xxx e-letter", //nepovinné, pokud chybí, předvyplní se z vašeho nastavení 
		"ReplyTo"=>"xxx@xxx.cz", //nepovinné, pokud chybí, předvyplní se z vašeho nastavení 
		"ReplyToName"=>"xxx e-letter", //nepovinné, pokud chybí, předvyplní se z vašeho nastavení 
		"odeslat_start"=>"2013-12-20 20:20:20", //nepovinné  jinak Y-m-d H:i:s
		"emailto_before"=>"me@me.cz", //nepovinné
		"emailto_after"=>"me@me.cz", //nepovinné
		"embedLocalImages"=>true,//nepovinné
		"linkWebVersion"=>true,//nepovinné
	),array(
		"Obsah" => "Blabla" //nepovinný parametr $obsah = můžete poslat přednastavený text, $key => "obsah", kde $key je alias vašeho obsahové bloku
	) //nepovinný parametr $obsah = můžete poslat přednastavený text, $key => "obsah", kde $key je alias vašeho obsahové bloku
);
$report = $apiCall->SendRequest();
if (!$report)
{	
	echo $apiCall->getError();	
}else {	
	echo 'Akce proběhla úspěšně.';	
} 
?>
</file>

=== Založení nového mailingu ===

Přidání nového mailingu \\
<code>
**MailingAdd**
param str $predmet\\
param int $sablona\\
param int or array of ints $skupiny\\
param bool $embedLocalImages\\
param array $data = From, FromName, ReplyTo, ReplyToName, odeslat_start, emailto_before, emailto_after, linkWebVersion\\
param array $obsah\\
</code>
<file php MailingAdd.php>
<?php 
include('API_class.php');

$apiCall = new MassMailingAPI();
$apiCall->setSessionID("Vaše Příchozí SessionID");
$apiCall->MailingAdd(
	"Předmět mailingu",
	5, //id šablony
	array(23,21), //ID skupin, které dostanou mailing - array nebo samostatný integer.
	true, //lokální obrázky v těle při odeslání
	array(
		"From"=>"mailing@xxx.cz", //nepovinné, pokud chybí, předvyplní se z vašeho nastavení 
		"FromName"=>"xxx e-letter", //nepovinné, pokud chybí, předvyplní se z vašeho nastavení 
		"ReplyTo"=>"xxx@xxx.cz", //nepovinné, pokud chybí, předvyplní se z vašeho nastavení 
		"ReplyToName"=>"xxx e-letter", //nepovinné, pokud chybí, předvyplní se z vašeho nastavení 
		"odeslat_start"=>"2013-12-20 20:20:20", //nepovinné  jinak Y-m-d H:i:s
		"emailto_before"=>"me@me.cz", //nepovinné
		"emailto_after"=>"me@me.cz", //nepovinné
		"linkWebVersion"=>true,//nepovinné
	),array(
		"Obsah" => "Blabla" //nepovinný parametr $obsah = můžete poslat přednastavený text, $key => "obsah", kde $key je alias vašeho obsahové bloku
	) //nepovinný parametr $obsah = můžete poslat přednastavený text, $key => "obsah", kde $key je alias vašeho obsahové bloku
);
$report = $apiCall->SendRequest();
if (!$report)
{	
	echo $apiCall->getError();	
}else {	
	echo 'Mailing založen.';	
} 
?>
</file>

==== Složitější příklady použití ====
=== Formulář na přidání odběratele na webu ===

**Tento příklad je úplně základní, je třeba udělat nějakou základní protispamovou ochranu (např. captcha, javascript, ...) a kontrolu, zda se jedná o email.**

<file php MailingAdd.php>
<?php

if(isset($_POST["submitMe"]) && !empty($_POST["newMember"]))
{

	$apiCall = new MassMailingAPI();
	$apiCall->setSessionID($C_MM_sessID);
	$apiCall->setDefaultSkupina(9); //nastaví defaultní skupinu odběratele, takže není nutné jí dávat jako parametr v UserEdit();
	$apiCall->UserEdit(trim($userek[$_POST["newMember"]));
	$report = $apiCall->SendRequest();
	if (!$report)
	{	
		echo $apiCall->getError();	
	}else {	
		echo 'Uživatel vložen.';	
	} 
}

?>

<form action="" method="post">
<label>Váš email</label>
<input type="text" name="newMember" value="" />
<input type="submit" name="submitMe" value="Přihlásit k odběru" />
</form>
</file>