Nastavení API
Základem pro komunikaci s naším API rozhraním jsou identifikační údaje – API ID a MD5 kód. V nastavení integrace se tak nejen dozvíte tyto údaje, ale máte zde i možnost MD5 kód změnit v případě, že by došlo k jeho vyzrazení.
POZOR – V případě, že změníte váš MD5 kód, přestanou veškeré vaše aplikace, ktere využívají současný kód fungovat do doby, než dojde k zadání nového kódu na straně aplikace.
API rozhraní z bezpečnostních důvodů akceptuje spojení pouze z povolených IP adres (či síťových rozsahů). Z tohoto důvodu je nezbytné nejprve zde přidat jednotlivé IP adresy, případně podsítě, či sítě v této části. Formát zadávání síťových rozsahů je pak pomocí netmasky IP adresy, tzn. např. 192.168.1.0/24 pro povolení celého rozsahu 192.168.1.0-255.
POZOR: Bezpečnost API rozhraní je plně pod Vaší kontrolou a je nezbytné udržovat tento seznam aktuální, aby nedošlo ke zneužití vašeho účtu. Nedoporučujeme ani povolení přístupu z celého internetu zadáním sítě 0.0.0.0/0 – toto řešení se může nabízet tam, kde se využívají cloudové služby, ale měli byste spíše kontaktovat vašeho poskytovatele cloudu a získat statickou IP, či vlastní podsíť.
Aby bylo možné na vašem webu úspěšně implementovat Event API, jež je potřebné pro měření konverzí a remarketingové kampaně, je nutné si nejprve nechat verifikovat referery, na kterých bude Event API nasazeno.
Jednoduše přidáte název referera a následně na serveru vytvoříte soubor se jménem a obsahem dle instrukcí a necháte ověřit.
POZOR: Ověření referera (tzn. zdroje odkud přichází volání) je klíčovým bezpečnostním prvkem, který nelze vynechat. Neni proto možné ani pro vývojové a testovací účely využívat zdroje, jež není možné síťově ověřit (např. localhost). Volání Event API z neautorizovaného zdroje vždy vrací odpověď 403 Forbidden.
Sady tagování odkazů
Obecně je trackování třetími stranami prováděno předáním identifikačních informací v odkazu na web, známých také jako UTM parametry. Platforma pro analýzu webových stránek nebo jakýkoli systém třetích stran poté použije informace předávané v URL k identifikaci referera (zdroje) návštěvy a jeho dalšímu sledování a reportování. Pro vaše kampaně si můžete vytvořit různé sady. Více o trackování odkazů se dočtete ZDE.
Přímo v prostředí Mailkitu si můžete nastavit napojení na systémy třetích stran, abyste do nich mohli předávat data k jejich dalšímu zpracování. Začněte kliknutím na tlačítko “Přidat spojení” a vyberte platformu, se kterou chcete napojení vytvořit.
Google BigQuery je nástroj pro analýzu dat a manipulaci s nimi. Předaná data tak můžete dále zpracovávat a vytvářet si z nich další specifické reporty, dashboardy a analýzy.
Pro nastavení je třeba vložit JSON konfiguraci s přístupovými údaji tzv. Servisního účtu (Service Account), jenž byl pro tento účel založen v Google Cloud Platform. Daný servisní účet musí mít práva pro správu daného BigQuery projektu (BigQuery User) i ke spouštění dávek (BigQuery Job User).
Recombee
Tato integrace slouží k propojení obou systémů za účelem získávání dat z Recombee a jejich plnění do šablon vašich kampaní (pomocí plug-inu Recombee) a zároveň lze využít automatické předávání eventů a zasílat data do Recombee automaticky, aniž by bylo potřeba další kód od Recombee nasazovat. Samozřejmě nutným předpokladem je Recombee používat a mít v Recombee účtu naimportovaný produktový feed (Catalog Feed).
Pro nastavení spojení je třeba v prvním kroku zadat ID databáze (najdete v nastavení Recombee jako název databáze (API Identifier), v druhém kroku pak Soukromý Token (Private Token).
Jak bylo uvedeno výše, tato integrace umožňuje také posílání dat do Recombee – za tímto účelem stačí zaškrtnout checkbox “Předávat eventy”.
Pokud je nasazené naše EventAPI a pole je zaškrtnuté, budou automaticky všechny akce/eventy (přidání do košíku, nákupy, atd..) zasílány do Recombee, kde mohou vznikat další rekomendace. Pokud tedy máte na svých stránkách nasazeno naše Event API, nemusíte nasazovat skripty od Recombee, protože Mailkit data z eventů automaticky předá.
Tato integrace umožňuje posílat automaticky informace o odeslaných (doručených, nedoručených,...) e-mailech a interakcích příjemců do Exponey, kde tyto informace mohou být použity v dalších scénářích.
Pro úspěšné propojení je potřeba v prvním kroku zadat URL endpointu, v druhém kroku pak ID API klíče a API heslo.
POZOR: Nezapomeňte na to, že napojení na systémy třetích stran vede k předávání osobních údajů třetí straně. Je proto vaší povinností informovat subjekty zpracování osobních údajů o všech zpracovatelích, kteří jsou zapojeni do zpracování osobních údajů.
Kliknutím na ikonu tužky
URL adresy webhooků
Mailkit umožňuje předávání dat na vlastní rozhraní klienta pro další zpracování pomocí webhooků. V současné době jsou podporovány webhooky pro evidenci souhlasu a to odděleně pro získání souhlasu a odebrání souhlasu, tzn. Subscribe a Unsubscribe. V rámci každého webhooku je předáván rozdílný rozsah informací v podobě JSON struktury předané POST voláním na URL uvedenou v menu Profil –> Integrace v sekci URL Adresy webhooků.
Subscribe:
V rámci webhooku pro přihlášení jsou v POST volání předány následující hodnoty v JSON struktuře:
EMAIL – e-mailová adresa
ID_EMAIL – ID e-mailové adresy
DATE – datum a čas přidání e-mailové adresy ve formátu RRRR-MM-DD HH:MM:SS
AUTH – SHA1 digest hash generovaný z řetězce složeného z DATE + EMAIL + API MD5, tzn. Např. “2020-11-25 11:20:03test@example.com1234567890abcdef1234567890” (předtím, než je hash vygenerován, je e-mailová adresa převeden na tvar s malými písmeny, tzn. např. e-mail TEST@Example.com je převedeno na test@example.com)
IP – IP adresa, jež potvrdila souhlas
IP_ORIG – IP adresa, jež potvrdila souhlas
ID_ML - ID seznamu příjemců
CHANNEL – kanál, kterým byl potvrzen souhlas
UA – user-agent-string zařízení, kterým byl udělen souhlas
DATE_REQUEST – datum a čas, kdy byl vytvořen požadavek o přihlášení
UA_REQUEST – user-agent-string zařízení, kterým byl vytvořen požadavek o přihlášení
IP_REQUEST – IP adresa, ze které byl proveden požadavek o přihlášení
IP_ORIG_REQUEST – IP adresa, ze které byl proveden požadavek o přihlášení
URL_CODE – ověřovací kód, kterým proběhlo potvrzení
FIRST_NAME – jméno
LAST_NAME – příjmení
FAX – fax
GENDER – pohlaví
MOBILE – mobilní telefon
NICK_NAME – přezdívka
PHONE – telefon
PREFIX – titul
REPLY_TO – adresa pro odpovědi
STATE – kraj
STREET – ulice
VOCATIVE – oslovení
ZIP – PSČ
CITY – město
COMPANY – firma
COUNTRY – země
CUSTOM1 – custom pole č.1
...
CUSTOM25 – custom pole č.25
Unsubscribe:
Při odhlášení či změně témat jsou v POST předány tyto hodnoty v JSON struktuře:
EMAIL – e-mailová adresa příjemce, nebo telefonní číslo
ID_EMAIL – ID e-mailové adresy
CHANNEL – komunikační kanál (email/sms)
DATE – datum a čas odhlášení ve formátu RRRR-MM-DD HH:MM:SS
AUTH – SHA1 digest hash generovaný z řetězce složeného z DATE + EMAIL + API MD5, tzn. Např. “2020-11-25 11:20:03test@example.com1234567890abcdef1234567890” (předtím, než je hash vygenerován, je e-mailová adresa převeden na tvar s malými písmeny, tzn. např. e-mail TEST@Example.com je převedeno na test@example.com)
IP – IP adresa, ze které proběhlo odhlášení (pokud je k dispozici)
IP_ORIG – IP adresa, ze které proběhlo odhlášení (pokud je k dispozici)
ID_ML – ID seznamu příjemců, na který byla odhlášena
ID_SEND – ID rozesílky, ze které se příjemce odhlásil
ID_MESSAGE – ID kampaně, ze které se příjemce odhlásil
ID_TOPIC_ACTIVE – seznam aktivních témat příjemce (v případě, že se jedná o změnu témat)
ID_TOPIC_INACTIVE – seznam odhlášených témat příjemce (v případě, že se jedná o změnu témat)
TIMEOUT – délka dočasného odhlášení (počet dní)
EXPIRE – datum a čas, kdy dojde k deaktivaci dočasného odhlášení
METHOD – metoda, kterou došlo k odhlášení (link_in_mail,manual, spam_report, list-unsubscribe_mail, api_unsubscribe, list-unsubscribe_oneclick, timeout)
UNSUBSCRIBE_ANSWER – zvolený důvod odhlášení
UNSUBSCRIBE_NOTE – v případě uvedení textového důvodu jeho text
Nezapomeňte, že ne vždy musí být všechny tyto hodnoty naplněny, a tak mohou být případně prázdné.
Zabezpečení webhook rozhraní
Rozhraní, které přijímá webhook volání z aplikace Mailkit, je vhodné zabezpečit proti zneužití. Rozhraní pro webhooky MUSÍ používat zabezpečené spojení https s validním certifikátem. Nejnižší možnou ochranou je samozřejmě zajistit, že se nikdo nedozví URL adresu tohoto rozhraní. Autenticitu požadavků je vhodné ověřovat pomocí podpisu ve větvi AUTH, který se počítá z hodnot DATE, EMAIL a API klíče, který najdete ve vašem účtu. Po spojení těchto hodnot do jednoho řetězce se z tohoto spočítá SHA1 podpis, který se musí shodovat s hodnotou AUTH. Tímto je zajištěno, že nikdo bez znalosti vašeho API hashe nebude schopen do vašeho webhooku poslat neautorizovaná data.
Pro omezení přístupu k rozhraní pouze ze serverů služby Mailkit omezte přístup pouze na IP adresy ze sítě 185.136.200.0/22. Mailkit operuje s vlastní infrastrukturou a nevyužívá žádných serverů třetích stran ani cloudových služeb, a proto je jisté, že požadavky přicházející z této sítě, jsou validními požadavky. Stále je však vhodné mít implementované i ověřování podpisu AUTH. V případech, kde z důvodu interních bezpečnostní politik není zabezpečení pomocí IP adres dostačující, doporučujeme použít zabezpečení pomocí klientských certifikátů.
Zabezpečení pomocí klientských certifikátů
Pro účely ověření autenticity volání je možné, aby volání webhooku bylo autorizováno pomocí klientských SSL certifikátů. Za tímto účelem je možné využít standardních certifikátů Mailkitu, nebo certifikátů dodaných klientem. V případě použití standardních certifikátů je nutné nainstalovat veřejný certifikát Mailkitu dostupný na adrese https://static.mailkit.eu/mailkit_webhook_ca.crt na server klienta s rozhraním pro webhooky a nastavit jeho používání (uvádíme příklad pro nastavení na serveru Apache):
SSLVerifyDepth 1
SSLCACertificateFile "/etc/ssl/mailkit_webhook_ca.crt"
V případě potřeby používat vícero certifikačních autorit je vhodné nahradit direktivu SSLCACertificateFile tímto řádkem:
Do daného adresáře je možno umístit více kořenových certifikátů, pak je třeba spustit i další příkaz:
Jakmile bude certifikát nasazen na serveru, je možné požádat o kontrolu a aktivaci e-mailem na adresu helpdesk@mailkit.com.
Aby bylo možné použít vlastní klientské SSL certifikáty, musí poskytovatel rozhraní webhooku poskytnout Mailkitu klientský certifikát a klíč ve formátu RSA zabezpečeného heslem, který bude předán bezpečnou cestou odděleně od certifikátu.
Vytvoření certifikátů pomocí openssl
Je možno vygenerovat self-signed certifikát takto:
openssl req -days 3650 -new -x509 -key ca.key -out ca.crt
Tento ca.crt bude používán webovým serverem na adrese https://url_rozhrani_webhooku, tj. např. je třeba nasměrovat níže uvedenou direktivu SSLCACertificateFile. Pokud již používáte na tento účel jiný CA certifikát, je možno jej použít, budete však potřebovat i klíč příslušející k tomuto certifikátu.
Vytvoření klíče s heslem a CSR:
Následně je možno vytvořit klientský certifikát:
CAcreateserial -out mk.eu.crt
Pokud máme certifikát a klíč vytvořený výše uvedeným způsobem (zde předpokládáme použití výše uvedených příkazů), můžeme je ověřit:
Dalším krokem je zajistit ověření autenticity certifikátu na serveru rozhraním webhooku.
Příklad konfigurace ověřování certifikátu na serveru Apache:
SSLVerifyDepth 1
SSLCACertificateFile "/etc/ssl/mailkit_webhook_ca.crt"
Parametr SSLCACertificateFile musí obsahovat cestu k souboru vygenerovanému jako certifikátu autority při generování klíčů.
Nyní doporučujeme otestovat, že server vyžaduje klientský certifikát:
Je-li vše v pořádku, soubory mk.eu.crt a mk.eu.key je potřeba zaslat na Helpdesk. Tyto soubory budou následně nasazeny na straně Mailkitu. Heslo k certifikátu (pokud bylo při vytváření zadáno) následně zašlete odděleně (např. SMS) s informací o ID ticketu z Helpdesku, které bylo přiděleno vaší žádosti o nasazení certifikátu.
Na straně Mailkitu dojde k dekódování certifikátu a následnému překódování a uložení certifikátu systémovým heslem, které je pro každého zákazníka jiné.
Funkčnost rozhraní a ověřování certifikátu pak lze simulovat a ověřit např. pomocí utility curl:
-d '{"ID_ML":"1234","ID_MESSAGE":"12345","METHOD":"api_unsubscribe",
"UNSUBSCRIBE_NOTE":"abc","TIMEOUT":"","IP":"1.2.3.4",
"IP_ORIG":"0.0.0.0","ID_EMAIL":"123456","EMAIL":"test@nekde.cz",
"EXPIRE":"","ID_TOPIC_ACTIVE":"0","ID_TOPIC_INACTIVE":"0",
"ID_SEND":"123","DATE":"2018-08-31 12:33:15","UNSUBSCRIBE_ANSWER":""}'
Ve volání je v parametrech --cert a --key cesta k souborům obsahujících vygenerovaný certifikát a klíč. Do url je pak nutné doplnit adresu k vlastnímu rozhraní, které má být předmětem testování.
Poskytovatel rozhraní musí zajistit ověření autenticity certifikátu a pouze v případě platného požadavku odpovědět stavovým kódem 200, 202 nebo 204. Odpovědi s jiným stavovým kódem vyvolají opakování volání webhooku se zvyšující se prodlevou až do okamžiku expirace po 24 hodinách, kdy dojde k deaktivaci webhooku jako celku.
