Obsah

Rozesilam.cz API dokumentace

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

protected $MM_apiURL = "http://www.rozesilam.cz/API_connect.php";

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

2017-11-19 - 2018-11-19
* velké změny

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.

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>';
 ?>

Statistiky

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

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

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.";
 
	}
 
} ?>

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.

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

Jednoduché přidání/editace nového uživatele

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";
} ?>

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!

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";
} ?>

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

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";
} ?>

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ě)

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";
} ?>

Skupiny

Výpis skupin

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

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í.";
 
	}
 
} ?>

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.

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

SkupinaAdd($nazev,$info);

Jednoduché přidání/editace nové skupiny

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";
} ?>

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.

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";
} ?>

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í

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";
} ?>

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

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

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ů";
} ?>

Mailingy

Odeslání testu

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

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";
} ?>

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();

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";
} ?>

Získání seznamu mailingů

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

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í.";
 
	}
 
} ?>

Smazání Mailingu

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

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";	} 
?>

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)

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";	
} 
?>

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.

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>';	
} 
?>

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.

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>';	
} 
?>

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

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ě.';	
} 
?>

Založení nového mailingu

Přidání nového mailingu

**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\\

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.';	
} 
?>

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.

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>