API

Přístup na https://api.mailservis.cz?key=. Klíč je pro každého klienta unikátní, zobrazen je po přihlášení do klientské sekce na mailservis.cz/klient

Api umožňuje zobrazení, vytváření a úpravu šablon, adresáře a distribucí.


https://api.mailservis.cz/get/clientinfo?key=XXX
        

Šablona HTML šablona rozesílaného newsletteru. Lze používat %% pro nahrazení výrazů v průběhu rozesílaní údaji evidovanými u jednotlivého adresáta.

Adresář Adresáti s přiřazenými štítky, evidence odhlášení a údajů k nahrazení.

Distribuce Rozesílka mailů – kombinace šablony a výběru adresátů.



/get

/get/clientinfo - Informace o klientovi

{
	"status":{
		"status_code":"ok",
		 "status_info":"client info"
	},
	"response":[{
		"id":"0",
		"name":"Test client",
		"logo":"image link",
		"domain":"doaim.tld",
		"limitleft":"100000",
		"limitset":"1",
		"limitval":"100000",
		"apikey":"XXXXXXXXXXXXXXXXXX",
		"owner":{
			"id":"7",
			"mail":"owner@mail",
			"isActive":"1",
			"isDel":"0",
			"name":"Owner name",
			"photo":"image link",
			"last":"2017-11-01 12:36:23",
			"created":"2015-11-11 16:17:21",
			"note":""
		},
		"note":"",
		"date":"2015-07-23 13:16:36",
		"isActive":"1",
		"isDel":"0",
		"DKIM":"1",
		"SPF":"1",
		"FBL":"1",
		"importurl":"",
		"unsubscribeurl":""
	}]
}

/get/distlist - Seznam distribucí

Seznam lze filtrovat parametrem id k získání konkrétní distribuce – https://api.mailservis.cz/get/distlist?id=1&key=XXX

{
	"status":{
		"status_code":"ok",
		"status_info":"distribution list"
	},
	"response":[{
		"id":"1",
		"updated":"2017-11-01 04:45:26",
		"client":"1",
		"user":"1",
		"mess":"1",
		"subject":"Subject",
		"utm":"",
		"alias":"info@domain",
		"name":"Name",
		"celkem":"3155",
		"sent":"3155",
		"startTime":"2015-07-23 16:00:00",
		"endTime":"2015-07-23 16:55:00",
		"isDel":"0",
		"created":"2015-07-23 15:30:48"
	},
	{
		"id":"42",
		...
	},
	...]
}

/get/templatelist - Seznam šablon

Seznam lze filtrovat parametrem id k získání konkrétní distribuce – https://api.mailservis.cz/get/templatelist?id=1&key=XXX

{
	"status":{
		"status_code":"ok",
		"status_info":"template list"
	},
	"response":[{
		"id":"11",
		"name":"",
		"subject":"Subject",
		"client":"11",
		"last":"2015-07-23 15:25:55",
		"lang":"1",
		"isDel":"0",
		"bySmart":"0",
		"done":"1"
	},
	{
		...
	}]
}

/get/bottommesslist - Seznam patiček pro odhlášení

Seznam lze filtrovat parametrem id k získání konkrétní patičky - https://api.mailservis.cz/get/bottommesslist?id=1&key=XXX

{
	"status":{
		"status_code":"ok",
		"status_info":"bottom mess list"
	},
	"response":[{
		"id":"10",
		"nazev":"uprava pro odhlaseni",
		"text":"Pokud si již nepřejete dostávat tato sdělení,
		 klikněte %%zde%%",
		"headtext":"Zobrazit v prohlížeči? %%Klikněte zde%%",
		"otazky":"Již nechci dostávat tyto zprávy;Nikdy jsem se nepřihlá...",
		"client":"11",
		"isDel":"0"
	}]
}

/get/labelslist - Seznam štítků použitých v adresáři

Seznam lze filtrovat parametrem id k získání konkrétního štítku – https://api.mailservis.cz/get/labelslist?id=1&key=XXX

{
	"status":{
		"status_code":"ok",
		"status_info":"labels list"
	},
	"response":[{
		"id":"4539",
		"name":"Z přihlašovacího formuláře"
	},
	{
		...
	}]
}

/get/contactlist - Kompletní adresář

Seznam lze filtrovat parametrem id k získání konkrétního kontaktu – https://api.mailservis.cz/get/contactlist?id=1&key=XXX

Seznam lze filtrovat parametrem label k získání seznamu ke konkrétnímu štítku – https://api.mailservis.cz/get/contactlist?label=1&key=XXX

{
	"status":{
		"status_code":"ok",
		"status_info":"contact list"
	},
	"response":[{
		"id":"499017",
		"client":"11",
		"mail":"prijemce@email.cz",
		"domain":"email.cz",
		"unsubscribe":"0",
		"source":"0",
		"isDel":"0",
		"labels":[{
			"id":"4561",
			"name":"Spotřební zboží"
		},
		{
			"id":"4563",
			"name":"Další štítek"
		}],
		"replace":[{
			"name":"osloveni",
			"val":"pan"
		},
		{
			"name":"tit",
			"val":""
		},
		{
			"name":"name",
			"val":"Jan"
		},
		{
			"name":"surname",
			"val":"Novák"
		},
		{
			"name":"phone",
			"val":"12345679"
		}]
	},
	{
		...
	}]
}


/set

/set slouží k odesílání dat v mailservisu. V případě specifikování "id" dojde k aktualizaci stávajícího záznamu, v opačném případě dojde k založení záznamu a vrácení nového id v response.

/set/contact - Vytvoření/aktualizace příjemce

JSON pole v parametru data – https://api.mailservis.cz/set/contact?&key=XXX&data=(JSON)

Novinka od 25. 5. 2018: Nový parametr verified, který určuje validitu kontaktu dle GDPR.

Povinné položky: mail. V případě prázdného ID bude mail hledán v adresáři a případně vytvořen. Unsubscribe výchozí 0, verified výchozí 0, kvůli GDPR nutné získání 1, štítky budou buď přiřazeny nebo vytvořeny a přiřazeny. Názvy hodnot pro nahrazení libovolné, avšak nutné počítat s tím, že budou používány v šabloně ve formátu %%nameofval, proto nejlépe dohromady a bez diakritiky.

{
	"id":"499017",
	"mail":"prijemce@email.cz",
	"unsubscribe":"0",
	"verified":"1",
	"labels":["Spotřební zboží",
	"Další štítek",
	...],
	"replace":[{
		"name":"osloveni",
		"val":"pan"
	},
	{
		"name":"tit",
		"val":""
	},
	{
		"name":"name",
		"val":"Jan"
	},
	{
		"name":"surname",
		"val":"Novák"
	},
	{
		"name":"phone",
		"val":"12345679"
	}]
}
//odhlášení příjemce {
	"mail":"prijemce@email.cz",
	"unsubscribe":"1"
}

/set/label - Vytvoření/aktualizace štítku

JSON pole v parametru data – https://api.mailservis.cz/set/label?&key=XXX&data=(JSON)

Povinné položky: name. V případě prázdného ID bude štítek vytvořen, v opačném případě název štítku aktualizován.

{
	"id":"4604",
	"name":"Testovací název štítku"     // bude aktualizován
} 
{
	"id":"",
	"name":"Testovací název štítku"     // bude vytvořen
}
{
	"name":"Testovací název štítku"     // bude vytvořen
}

/set/template - Vytvoření/aktualizace šablony

Šablona bude vložena jako HTML/CKEditor šablona. Nebude možné ji upravovat ve SmartEditoru.

JSON pole v parametru data – https://api.mailservis.cz/set/template?&key=XXX&data=(JSON)

Povinné položky: name, mess, subject. V případě prázdného ID bude šablona vytvořena. Výchozí ID odhlašovací zprávy je 0

{
	"id":"",
	"name":"Nazev sablony",
	"Subject":"Predmet mailu",
	"mess":"html zpravy",
	 "bottom":"id odhlasovaci zpravy"
}

/set/send - Odeslání rozesílky na definované adresáty se zvolenou šablonou

Povinné položky: mess. Mess možné definovat jako ID existující šablony nebo pomocí jednorázového HTML (pokud je html velké a přesahuje povolenou délku url, je možné definovat jako contenturl, ze které bude šablona stažena). Výchozí contactlist jsou všichni adresáti, jinak specifikovat pomocí id štítků nebo specifikovat konkrétní mailové adresy, výchozí sendtime je aktuální hodina, výchozí alias je "info". Send time je možné určovat> aktuální čas a s přesností na hodiny. Na případné minuty nebude brán ohled.

Po vytvoření rozesílky bude vráceno její ID, nelze ji však zpětně upravovat.

{
	"sendtime":"2017-11-28 12:00",
	"mess":{
		"id":"11"
	},
	 "contactlist":{
		"labels":["12",
		"13",
		"..."]
	},
	 "alias":"info",
	 "utm":"newsletter01"
}
{
	"sendtime":"2017-11-28 12:00",
	"mess":{
		"subject":"predmet",
		"content":"html zpravy",
		"unsubmess":"42"
	},
	 "contactlist":{
		"labels":["12",
		"13"]
	},
	 "alias":"info",
	 "utm":"newsletter01"
}
{
	"sendtime":"2017-11-28 12:00",
	"mess":{
		"subject":"predmet",
		"contenturl":" url link na stažení html zprávy"
	},
	 "contactlist":{
		"labels":["12",
		"13"]
	},
	 "alias":"info",
	 "utm":"newsletter01"
}
{
	"sendtime":"2017-11-28 12:00",
	"mess":{
		"subject":"predmet",
		"contenturl":" url link na stažení html zprávy"
	},
	 "contactlist":{
		"mails":["mail1@domain",
		"mail2@domain",
		"mail3@domain",
		"..."]
	},
	 "alias":"info",
	 "utm":"newsletter01"
}
{
	"sendtime":"2017-11-28 12:00",
	"mess":[{
		"content":"html zpravy"
	}],
	 "contactlist":[{
		"mails":["mail@test.cz",
		"mail2@example.cz",
		"..."]
	}],
	 alias:"info",
	 "utm":"newsletter01"
}


PHP Vzor

Vzor php kódu pro volání API:

V příkladu se posílá šablona dostupná na url, zprávu odesíláme hned a na přímo určenou sadu mailů.


<?php

$apikey = "testkey-123456789XYZdemomailsrvs";

//priprava dat pro api
$data = array(
    "sendtime" => date("Y-m-d H:00"),
    "mess" => array(
        "subject" => "Testovací zpráva",
        "contenturl" => "https://api.mailservis.cz/testtemplate"
    ),
    "contactlist" => array(
        "mails" => array("mail1@netservis.cz", "mail2@netservis.cz", "mail3@netservis.cz")
    ),
    "alias" => "info",
    "utm" => "testmail"
);

//volani api
$tmp = file_get_contents("https://api.mailservis.cz/set/send/?key={$apikey}&data=".urlencode(json_encode($data)));

//vysledek
var_dump($tmp);
        




NETservis s.r.o. © 2014 - 2020 NETservis.cz WebRedakce.cz Přístup pro klienty Nástroje pro vývojáře MAILservis