Prepojte sa s Mailkit knižnicou
Máte problémy s doručiteľnosťou mailov z e‑shopu? Ušetrite si prácu s napojovaním Mailkit API do vlastnej aplikácie a použite našu PHP/Nette knižnicu. Uvoľnili sme ju zdarma na stiahnutie na GitHube.
Problémy s kódovaním e‑mailov
Z pohľadu bežného užívateľa je e‑mail jednoduchá vec. Denne nám ich do schránky prídu desiatky a napísanie/odoslanie nie je žiadna veda. Z technického hľadiska to ale tak jednoduché nie je. Grafik musí navrhnúť ich vzhľad, HTML kód sa píše v tabuľkách, obsahuje inline styly, a ak chceme niečo pridať alebo upraviť, je to dosť často veľký boj. A nie každý vývojár má u seba nainštalovaný mailserver, z ktorého si nechá pri vývoji aplikácie zasielať testovacie správy.
Ukážme si to na príklade, kedy chceme zákazníkovi odoslať informácie o spôsobe platby. Ak si vybral prevod na účet, musíme mu poslať číslo účtu, na ktorý objednávku zaplatí. U platby kartou ho ale vôbec nepotrebuje a u osobného odberu skôr ocení mapku s lokáciou predajne. Programátor tak musí prácne rozdeliť šablóny, doplniť premenné a pridať podmienky, ktoré celý kód značne zneprehľadňujú a znepríjemňujú tým prácu. To ani nehovorím o prípadoch, kedy sa zákazník, ktorému tieto šablóny implementujeme, rozhodne urobiť nejaké grafické zmeny.
Ako sa z toho nezblázniť? Jedným z riešení je používať webovú aplikáciu, ktorá umožňuje jednoduchú tvorbu šablón. Programátor už len nastaví, kedy se má správa posielať a akými dátami sa má naplniť. Určite sa kódovaním nezbavíme, ale minimálne si prácu spríjemníme ak „zas“ niekto príde a bude chcieť upraviť nejaký „detail“. V igloonete k tomu využívame Mailkit.
Prečo Mailkit?
Mailkit je český nástroj pre e‑mailing a SMS marketing, cez ktorý posielame klientom kampane. Osvedčil sa nám hlavne kvalitnou doručiteľnosťou a veľmi príjemnou prácou s drag and drop šablónami, ktoré je možné ľahko upraviť, presne podľa potrieb klienta.
Ďalšou výhodou je pokročilá segmentácia databáze kontaktov, na základe napríklad nákupného chovania. Môžete zacieliť kampane na najvernejších zákazníkov alebo naopak na tých, u ktorých je najväčšie riziko prechodu ku konkurencii. O úvode do RFM analýzy si prečítajte viac v článku „RFM: Analýza zákazníků v kostce“.
Prepojenie aplikácie s Mailkit knižnicou
Na základe spolupráce s Mailkitom sme vytvorili PHP a Nette knižnicu, ktorá ešte viac uľahčí prácu s posielaním e‑mailových kampaní. Pre prepojenie s vlastnou aplikáciou nepotrebujete nič zložito inštalovať, stačí jeden príkaz, ktorý pripraví prácu s API.
$ composer require igloonet/mailkit-api
Jednoduché, že? Ešte vás ale nejaká práca čaká. Získané prístupové údaje si pripravte podľa dokumentácie do Client.
$clientId = 'id'; $clientMd5 = 'md5'; $mailkitApi = new \Igloonet\MailkitApi\RPC\Client($clientId, $clientMd5);
Ak používate Nette Framework , stačí zaregistrovať len ako novú extension.
$ composer require igloonet/nette-mailkit-api extensions: mailkitApi: Igloonet\NetteMailkitApi\DI\MailkitApiExtension
Nastavenie prístupových údajov:
mailkitApi: clientId: '' clientMd5: ''
A nastavenie závislosti, napríklad takto:
class Mailer { /** @var \Igloonet\MailkitApi\MailkitApi */ private $mailkitApi; public function __construct(\Igloonet\MailkitApi\MailkitApi $mailkitApi) { $this->mailkitApi = $mailkitApi; } // ...
Blahoželáme, váš web je prepojený s Mailkitom a môžete začať využívať celú radu preddefinovaných metód pre prácu s užívateľmi. Poďme si ukázať pár praktických príkladov, ako je pridanie užívateľa do databáze newsletterov, odoslanie transakčného e‑mailu alebo webhooky.
Ako na databázu newsletterov?
Povedzme, že potrebujem pridať užívateľa do databáze za účelom zasielania newsletterov.
Pri klasickej implementácii sa zákazník na webe prihlási k odberu noviniek a systém odošle formulár, čo ho pridá do databáze. Následne mu príde e‑mail s potvrdzujúcim odkazom, na ktorý musí kliknúť. Do systému teda musíme implementovať funkčné generovanie týchto odkazov, možnosť ich úprav a priradenie k správnemu zákazníkovi. Ukážeme si, ako to ľahko urobiť pomocou našej knižnice.
//..... $userManager = $this->mailkitApi->getUserManager(); //..... </ pre>
Zavoláme metódu pridania užívateľa
//..... $user = new User('example@example.cz') $mailingListId '12345'; // id nášho mailinglistu pre newsletter // práve ono true na konci nám zabezpečí zaslanie overovacieho e‑mailu. $userManager->addUser($user, $mailingListId, true); //.....
A to je všetko. Zákazníka sme pridali do zoznamu, zaslal sa mu automaticky overovací e‑mail a už mu môžeme veselo posielať novinky a akcie z e‑shopu. Programátor len pridá uvedený kód do metódy, ktorá sa volá po odoslaní formulára. Ako bude výsledný potvrdzovací e‑mail vyzerať je úplne na vás.
Transakčné e‑maily
Ďalšou neoddeliteľnou súčasťou, kde ide dobre využiť spomínanú knižnicu, sú transakčné e‑maily. Využijeme messagesManager.
$messagesManager = $this->mailkitApi->getMessagesManager(); $message = new \Igloonet\MailkitApi\DataObjects\Message($user); $message->setBody('test messages'); $campaignId = 11111; //id kampane vytvorenej v rozhraní mailkit $result = $messagesManager->sendMail($message, $mailingList->getId(), $campaignId);
Tieto metódy môžeme štandardne využívať na zasielanie akýchkoľvek e‑mailov, ktoré aktuálne potrebujeme. Napríklad na napísanie aplikácie, ktorá nám bude zasielať v plánovaný čas nejakú kampaň.
Ale vráťme se k transakčným e‑mailom. Na začiatok si ich musíme zvalidovať priamo v Mailkite. Bližšie informácie o tomto postupe nájdete na schvalovanie transakčných kampaní. Pred nastavením si uvedomme, čo štandardne obsahuje väčšina e‑mailov o prijatí objednávky:
- meno a priezvisko osoby, ktorá objednávku spravila
- doručovacia a fakturačná adresa
- platobná metóda
- jednotlivé položky objednávky
- konečná cena
Ak by sme toto všetko naplnili pri volaní $message->setBody('test messages'); , tak naša template stráca zmysel a moc si nepomôžeme. S rýchlejšou implementáciou opäť pomôže knižnica.
Máme triedu User() , tak čo do nej rovno nepridať všetky potrebné informácie o užívateľovi:
$user = new User('example@example.cz');
$user->setFirstName('First');
$user->setLastName('Last');
$user->setStreet('Street 1');
$user->setZip('12345');
$user->setCity('City');
$user->setCountry('Country');
//... a pod.
Po vyplnení všetkých potrebných údajov môžeme na tieto položky pristupovať pomocou premenných priamo v templatovacom nástoroji Mailkitu. Celý tým, vrátane ľudí, čo sa v programovaní veľmi nevyznajú, tak dokáže tvoriť jednoducho a prehľadne templaty.
Na premennú, nastavenú v $user->setLastName('Last'); , pristúpime v templatovacom systéme Mailkitu takto: [LAST_NAME]. Pri odosielaní sa následne tento kúsok kódu zamení za meno užívateľa, ktorému sa tento e‑mail zašle. Veľmi šikovná vec je skloňovanie, ktoré obvykle slúží k osloveniu príjemcov. Od teraz ho už nemusíme implementovať, ale stačí použiť napríklad [SKLONUJ 5,j,1][LAST_NAME][/SKLONUJ]. Viac sa dozviete priamo v dokumentácií Mailkitu zoznam systémových tagov.
Je zrejmé, že premenné ako meno alebo adresa sú v Mailkite prednastavené. Čo ak ale chceme poslať zložitejší objednávkový e‑mail, kde sa pri platbe prevodom mení číslo účtu a variabilný symbol na základe zeme, odkiaľ objednávka prišla? Jednoducho si vytvoríme a nadefinujeme vlastné tzv. content premenné:
$messagesManager = $this->mailkitApi->getMessagesManager(); $message = new \Igloonet\MailkitApi\DataObjects\Message($user); $message->setTemplateVar('customTemplateVariable', "Naša vlastná premenná"));
Na vlastné premenné môžeme pristúpiť pomocou [% shared.customTemplateVariable -%]. Pomenovaniu a obsahu sa medze nekladú.
Akonáhle vytvoríme všetky potrebné premenné, sme s templatou spokojní a Mailkit ju schváli, nie je nič jednoduchšie ako danú správu začať posielať zavolaním nasledujúceho príkazu:
$messagesManager = $this->mailkitApi->getMessagesManager(); $campaignId = 11111; //id kampane vytvorenej v rozhraní mailkit $result = $messagesManager->sendMail($message, $mailingList->getId(), $campaignId);
S kombináciou vlastných a prednastavených premenných tak môžeme jednoducho posielať personalizované e‑maily presne podľa svojich predstáv.
Webhooky
Webhooky slúžia primárne k aktualizácii informácií v aplikácii. Povedzme, že máme zoznam odberateľov newsletterov a zákazník sa z neho rozhodne po poslednom hromadnom e‑maile odhlásiť. V pätičke jednoducho klikne na odkaz vygenerovaný Mailkitom a po potvrdení sa v systéme označí ako odhlásený. Hotovo.
Čo ale v prípade, že túto skutočnosť potrebujeme nejak komunikovať v e‑shope? Napríklad chceme, aby registrovaný zákazník vo svojom profile videl, či je k newsletteru prihlásený alebo nie. K tomu potrebujeme informáciu o tom, že sa odhlásil. Ako to urobiť ? Riešením je už ako tušíte použitie webhookov.
V podstate nejde o nič zložité, čo by sme neboli zvyknutí robiť na dennej báze. Musíme nejak vytvoriť možnosť prijímania požiadavkov na našom servere. Systému, z ktorého chceme dostávať tieto informácie, je treba povedať, na ktoré endpointy tieto informácie zasielať.
V Mailkitu máme možnosť zasielania dvoch akcií: Subscribe a Unsubscribe, a to formou Subscribe volania POST v podobe JSON štruktúry. V payloade tohoto POST volania nájdete všetky potrebné informácie. My sa staráme o správne spracovanie a uloženie informácií aplikáciou.
Vysvetlíme si to na Nette aplikacii. Špeciálne pre tento účel si vytvoríme presenter, v ktorom nám postačia akcie actionSubscribe a actionUnsubscribe, ktoré budú prijímať naše POST volanie. Takto aplikácia získa dve nové adresy, napríklad www.example.cz/webhooks/subscribe a www.example.cz/webhooks/unsubscribe. Je dôležité si uvedomiť, že takto implementované webhooky majú jeden zásadný problém - na tieto endpointy môže zasielať informácie v podstate každý, kto pozná URL adresu. Preto by som doporučoval obmedziť prístup všetkým, okrem IP adresy Mailkitu. Ešte lepšie riešenie ponúka priamo Mailkit - ide o zabezpečenie pomocou klientských certifikátov.
Ak máme aplikáciu správne zabezpečenú, tak posledný krok je spracovať volanie webhooku. K tomu nám pomôže predpripravená trieda WebHooksManager ktorý sa postará o validáciu a parsovanie payloadu.
//WebHook subscribe $jsonPayloadFromWebHook = '{EMAIL":"example@example.cz", "ID_EMAIL":"1", .......... }'; //Webhook payload $subscribeValueObject = $webHookManager->processSubscribe($jsonPayloadFromWebHook); //WebHook unsubscribe $jsonPayloadFromWebHook = '{EMAIL":"example@example.cz", "ID_EMAIL":"1", .......... }'; //Webhook payload $unsubscribeValueObject = $webHookManager->processUnsubscribe($jsonPayloadFromWebHook);
Obe volania metód processSubscribe a processUnsubscribe nám navrátia instancie triedy, ktorú ďalej spracujeme. Zákazník se tak v profile dozvie, či je zrovna prihlásený k newsletteru a ďalšou akciou to prípadne zmení.
Na ukážku to stačí, knižnica vie toho samozrejme omnoho viac. Ak sa v záplavách kódu strácate (a aj tak ste dočítali až sem), nezúfajte. Mailkitu sa budeme v jednom z ďalších článkov venovať aj z pohľadu marketingu.
