PodporaZnalostní báze

Integrace

Mailkit poskytuje rozsáhlé možnosti integrace a to jak prostřednictvím API ve formátu XML a JSON, tak pomocí Eventů probíhajících na webových stránkách a Webhooků, které mohou předávat data vaší aplikaci v reálném čase. Veškerá nastavení integrace probíhají v této sekci Profilu.

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í.
012integraceapi.PNG
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.

Povolené IP adresy

013povoleneIP.PNGAPI 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íť.

Povolené domény

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.
014povolenedomeny.PNG

URL adresy webhooků

Mailkit umožňuje předávání dat na vlastní rozhraní klienta pro další zpracování pomocí webhooku. 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ů.
webhooks_cz.png

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
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
ID_EMAIL - ID e-mailové adresy
DATE - datum a čas odhlášení ve formátu RRRR-MM-DD HH:MM:SS
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í. Nejnižší možnou ochranou je samozřejmě zajistit, že se nikdo nedozví URL adresu tohoto rozhraní. Mnohem bezpečnější je ale zajistit tuto adresu proti neautorizovaným přístupům, a to buď omezením přístupu k této adrese pouze z IP adres serverů Mailkit, nebo pomocí klientského SSL certifikátu.
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. 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):

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

SSLCACertificatePath "/etc/ssl"

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

/etc/ssl# c_rehash -v

Jakmile bude certifikát nasazen na serveru, je možné požádat o kontrolu a aktivaci e-mailem na adresu helpdesk@mailkit.eu.

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 genrsa -out ca.key 2048
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:

openssl req -days 3650 -new -newkey rsa:2048 -keyout mk.eu.key -out mk.eu.csr

Následně je možno vytvořit klientský certifikát:

openssl x509 -req -days 3650 -in mk.eu.csr -CA ca.crt -CAkey ca.key -
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:

curl -v --cert mk.eu.crt --key mk.eu.key https://url_rozhrani_webhooku

Je-li vše v pořádku, soubor 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:

curl -E --cert mk.eu.crt --key mk.eu.key https://url_rozhrani_webhooku
-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ího 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. 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.

Příklad konfigurace ověřování certifikátu na serveru Apache:

SSLVerifyClient require
SSLVerifyDepth 1
SSLCACertificateFile "ca.crt"

Parametr SSLCACertificateFile musí obsahovat cestu k souboru vygenerovanému jako certifikátu autority při generování klíčů.