MAILservis Developers

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ů.

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ů.

Kompletní specifikaci a celý výčet parametrů naleznete níže!


<?php

$apikey = "demo_7p4H6ydGi36MkpWUbr50";

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

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

V příkladu se vkládá nový ověřený kontakt do adresáře, například po odeslání objednávky.

Kompletní specifikaci a celý výčet parametrů naleznete níže!


<?php

$apikey = "demo_7p4H6ydGi36MkpWUbr50";

//priprava dat pro api
$data = array(
    "mail" => "jannovak@exapmle.com",
    "verified" => 1,
    "unsubscribe" => 0,
    "labels" => array(
            "Objednávky eshop"
            ),
    "replace" => array(
            "jmeno" => "Jan Novák",
            "osloveni" => "pane Nováku"
            ),
);

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

//vysledek
var_dump($tmp);

/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.

Limit na jedno pole replace je 1024 znaků na jeho hodnotu, 128 znaků na jeho název. Pro správné fungování by jednotlivé názvy proměných neměli být podřetězce jiných (například %%castka a %%castkacelkem)

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

/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/history - Seznam posledně odeslaných zpráv (distribucí) a odkaz na webview - zobrazení v prohlížeči. Doplněno odkazem na kompletní seznam, viz newslettery v prohlížeči.
- Možno používat parametr limit, výchozí počet distribucí je 20 posledních zpráv dle data rozeslání.
- Z výběru jsou vynechány zprávy menší než 50 odběratelů pro vyloučení zkušebních rozesílek.

Seznam lze filtrovat parametrem limit – https://api.mailservis.cz/get/history?key=XXX&limit=3

{
	"status":{
		"status_code":"ok",
		"status_info":"history list,
		 limit by 3 "
	},
	"response":{
		"more":{
			"href":"https://mailservis.cz/historie/cokolada.cz",
			"action":"Zobrazit všechny poslední newslettery"
		},
		"links":[{
			"id":"2887",
			"href":"https://mailservis.cz/webview?d=2887",
			"dateofsend":"23.6.2020",
			"subject":"Čokoládové zázraky se dějí v Hradci Králové🍫"
		},
		{
			"id":"2870",
			"href":"https://mailservis.cz/webview?d=2870",
			"dateofsend":"16.6.2020",
			"subject":"Čokoládové slevy jsou zase tady!🍫"
		},
		{
			"id":"2849",
			"href":"https://mailservis.cz/webview?d=2849",
			"dateofsend":"9.6.2020",
			"subject":"Single Origin – na cestě okolo světa🍫🌍"
		}]
	}
}

/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"
		}]
	},
	{
		...
	}]
}

API

PHP Vzor - Odeslání

PHP Vzor - Import

/set

/get