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 pro transakční zprávy umožňuje posílání transakčních e-mailů v dvou základních variantách:

"Jídelní lístek" Pravidelný unikátní obsah rozesílaný na všechny příjemce ale seskupený pod jednu transakci

"Roční vyúčtování" Jednorázová hromadná zpráva která má ale unikátní obsah pro každého příjemce

nad to lze vytvořit libovolné kombinace:

"Ukončení předplatného" Stejný obsah opakovaně rozesílaný na různé sady příjemců

"Hodnocení objednávky" Unikátní obsah rozesílaný postupně na příjemce kteří dokončili objednávku

Použití API pro transakční maily je stejné jako pužití základního API:

        https://api.mailservis.cz/method/query?key=api_key
        

Každá transakční zpráva musí být nejprve založena. Do založené trasakční zprávy lze přidávat obsahy/příjemce nebo jejich kombinace.

Good practices

Pro zprávu typu "Jídelní lístek" založíme jednu transakci kterou doplňujeme každý den novým obsahem na všechny příjemce

Pro zprávu typu "Roční vyúčtování" založíme transakci pro každý rozesílaný rok a poté do ní uložíme individuální obsahy s příjemci

Transakce do které není více než 30 dnů přidán nový obsah/příjemci nebo jejich kombinace je archivována

<?php

$apikey = "demo_7p4H6ydGi36MkpWUbr50";

//priprava dat pro api
$data = array(
    "transation" => "true",
    "mess":{
		"code":"DD9DCD97"
	},
    "alias" => "info",
    "utm" => "testmail"
);

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

//vysledek
$result = json_decode($tmp, true);
var_dump($result["response"]["transaction_id"]); //id transakce pro následné plnění
var_dump($result["response"]["transaction_code"]); //ověřovací kód transakce
        

Naplnění transakce přes POST:

Pozor! Protože s $_GET narážíme na limity délky url, je vhodné poslat pole $data metodou POST, obvzlášť pokud je součástí delší HTML obsah.

<?php

$apikey = "demo_7p4H6ydGi36MkpWUbr50";

//priprava dat pro api
$data = array(
        "transaction_id" => "8559",
        "transaction_code" => "ad6deb37",
        "contactlist" => array( "mails" => array("novakova@example.com")),
        "content" => "Vážená paní Nováková
Na vašem účtě je přeplatek 33Kč",
        "subject" => "Vyúčtování"
    );

//priprava POST requestu
$url = 'https://api.mailservis.cz/set/add-to-transaction/';
$payload = array(
        'key' => $apikey,
        'data' => json_encode($data));
$options = array(
        'http' => array(
            'header'  => "Content-type: application/x-www-form-urlencoded\r\n",
            'method'  => 'POST',
            'content' => http_build_query($payload),
        )
    );
$context  = stream_context_create($options);

//volani api
$result = file_get_contents($url, false, $context);

//vysledek
$result = json_decode($tmp, true);
        

/set/create-transaction

- Založení transakce probíhá stejně jako rozeslání běžné zprávy
- Při použití "contenturl" je nutné aby šablona obsahovala placeholder %%transactioncontent%%

Po vytvoření rozesílky bude vráceno její ID a kód pro přidávání e-mailů do transakce

{
	"transaction":"true",
	"mess":{
		"id":"11"
	},
	  "alias":"info",
	 "utm":"newsletter01"
}

{
	"transaction":"true",
	"mess":{
		"code":"AAABBBCCC"
	},
	  "alias":"info",
	 "utm":"newsletter01"
}

/set/add-to-transaction

- Přidání příjemce/obsahu do transakce
- Pro přidání je nutné znát její ID a Kód, ten vrací api při založení transakce
- Pokud ID/kód trasakce nemáte, najdete ho na přehledu historie po najetí na ikonu transakce.
- zpráva se rozešle (přidá do fronty k rozeslání) okamžite

Transakci lze doplnit několika způsoby:

Typ "Jídelní lístek"

Posíláme unikátní obsah bez definice příjemců = kompletní adresář. Obsah se při odeslání vloží do šablony definované

{
	"transaction_id":"99",
	"transaction_code":"ABCDEF",
	"subject":"Jídelní lístek na pondělí",
	"content":"Dnes<br> Knedlo vepřo zelo<br> Segedín<br> .... "
}

Typ "Roční vyúčtování"

{
	"transaction_id":"99",
	"transaction_code":"ABCDEF",
	"contactlist":{
		"mails":["mail1@domain"]
	},
	"content":"Vážená paní Nováková<br>Na vašem účtě je přeplatek 1Kč. ....."
}

Typ "Ukončení předplatného"

{
	"transaction_id":"99",
	"transaction_code":"ABCDEF",
	"contactlist":{
		"mails":["mail1@domain",
		"mail2@domain",
		....]
	},
	"content":"Vaše červencové předpaltné končí<br>Obnovte si ho na www. ....."
}

Typ "Hodnocení objednávky"

{
	"transaction_id":"99",
	"transaction_code":"ABCDEF",
	"contactlist":{
		"mails":["mail1@domain"]
	},
	"subject":"Ohodnoťte prosím objednávku AB2023-01",
	"content":"Ohodnotíte nám prosím vámi zakoupený jaderný reaktor? ....."
}

/get/transaction-templatelist

- Seznam šablon pro transakční e-maily

Seznam lze filtrovat parametrem id k získání konkrétní distribuce – https://api.mailservis.cz/get/transaction-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"
	},
	{
		...
	}]
}