Späť na blog

Reportovanie e-mailov v doMail

R. Pipík
R. Pipík
Aktualizované:

Pri dôležitých e-mailoch potrebujete vedieť aj to, ktoré správy sa nepodarilo doručiť. doMail zhromažďuje informácie o spracovaní, odoslaní aj výsledku doručovania. Môžete ich využiť v databázových reportoch, prijímať cez ActiveMQ alebo dostávať prehľad nedoručených správ e-mailom s CSV prílohou. Pomôžu vám opraviť kontaktné údaje, vyriešiť technickú chybu alebo zákazníka kontaktovať iným spôsobom.

Aké informácie doMail reportuje

Základom je vzťah požiadavka → beh spracovania → jednotlivé správy. Jedna požiadavka môže vytvoriť viac správ. Opakované spracovanie vytvorí ďalší beh, preto pri vyhodnocovaní sledujte aj jeho číslo.

Stav odoslania opisuje priebeh spracovania a odosielania. Stav doručenia dopĺňa informáciu o ďalšom výsledku: napríklad oznámenie o nedoručení, otvorenie cez TrackPixel alebo kliknutie na sledovaný odkaz cez TrackLink. Odoslaný e-mail môže mať zatiaľ neznámy stav doručenia. Ak správy v jednom behu majú rozdielne stavy doručenia, súhrnný stav behu môže byť nejednoznačný.

Požiadavka s dvoma behmi spracovania a viacerými e-mailmi v jednotlivých behoch.
Vzťah požiadavky, behov spracovania a jednotlivých e-mailov.

SMTP chyby a oznámenia o nedoručení

Nedoručenie sa môže zistiť pri odosielaní alebo až neskôr, keď príde oznámenie o nedoručení (NDR, označované aj ako bounce). doMail pri vyhodnocovaní používa kód aj text hlášky a zaraďuje príčiny do kategórií, napríklad neplatná adresa, plná schránka, zablokovaný účet, príliš veľká správa, odmietnutie bezpečnostnou politikou alebo problém so sieťou.

Rozšírené stavové kódy majú tvar 5.1.1. Trieda 4.x.x označuje dočasné zlyhanie a 5.x.x trvalé zlyhanie. Neznamená to však, že každý kód začínajúci päťkou označuje neexistujúcu adresu. Napríklad 5.1.1 označuje chybnú cieľovú adresu schránky, zatiaľ čo 5.7.1 odmietnutie doručenia z dôvodu oprávnení alebo politiky. Význam kódov definuje RFC 3463.

V prijatých oznámeniach sa však rovnaký problém objavuje pod rôznymi kódmi a formuláciami. Nasledujúca tabuľka zachytáva príklady hlášok súvisiacich s neexistujúcou alebo nedostupnou adresou. Ide o kombinácie prijaté od serverov; pri vyhodnocovaní treba čítať celý text, nielen kód.

Text prijatej hlášky obsahujePrijatý kód
user unknown4.1.1
domain not found4.1.8
cannot find your hostname4.7.2
5.1.25.0.0
domain is no longer used for mail5.0.0
address rejected5.0.0
mailbox not found5.0.0
invalid recipient5.0.0
no user5.0.0
does not exist5.1.1
email does not exist5.1.1
no mailbox here by that name5.1.1
notfound; recipient5.1.1
user does not exist5.1.1
user doesn't exist5.1.1
user unknown5.1.1
user unknown in virtual alias table5.1.1
user unknown5.1.2
undeliverable address5.1.7
mailbox unavailable5.2.0
no such mailbox5.2.0
mailboxinactive5.2.1
domain is disabled5.3.2
domain * does not exist5.4.2
address rejected5.4.2
does not exist5.4.3
no such user5.4.3
unknown user5.4.3
user unknown5.4.3
domain name not found5.4.4
nonexistent domain5.4.4
mailbox unavailable5.5.0
no such recipient5.5.0
mailbox unavailable5.5.2
no such recipient5.7.0
address does not exist5.7.1
invalid recipients5.7.1
mailbox not found5.7.1
mailbox unavailable5.7.1
no such user5.7.1
user does not exist5.7.1
user unknown5.7.1
user does not exist5.7.2

Preto report umožňuje zobraziť kategorizovaný detail aj pôvodnú SMTP hlášku. Pri odmietnutí z bezpečnostných dôvodov môže text odkazovať napríklad na SPF, DKIM, DMARC alebo blokovanie odosielateľa. Pri plnej schránke či neplatnej adrese bude potrebný iný postup než pri chybe nastavenia odosielania.

Reportovanie cez databázu

Reporty vám vieme pripraviť aj priamo v databáze podľa vašich potrieb.

Ak máte o túto možnosť záujem, kontaktujte nás na domail@domail.io. Dohodneme požadovaný obsah a reporty vám nastavíme na vašej inštancii doMail.

Notifikácie cez ActiveMQ

Ak má na zmenu stavu reagovať ďalší systém, doMail môže posielať JSON notifikácie do frontov ActiveMQ. Notifikácie pokrývajú priebeh spracovania aj zmeny stavu doručenia. Na začiatku spracovania sa udalosť týka behu požiadavky; pri jednotlivých správach obsahuje informácie o konkrétnej správe a adresátovi.

Notifikácie cez ActiveMQ poskytujeme po dohode. Ak máte o túto možnosť záujem, kontaktujte nás na domail@domail.io. Spoločne dohodneme spôsob prepojenia a notifikácie vám nastavíme na vašej inštancii doMail.

Notifikácia obsahuje čas udalosti a tieto hlavné časti:

  • header — ID požiadavky a behu, externý a systémový identifikátor, scenár a štatistické parametre.
  • requestProcessing — stav spracovania a doručenia na úrovni behu.
  • email — číslo správy, adresát a stavy konkrétnej správy; pri doručení aj dostupné SMTP údaje.

Časti requestProcessing a email sa vypĺňajú podľa úrovne udalosti, preto neočakávajte obe pri každej notifikácii. Formát opisuje JSON schéma notifikácií. V nadväzujúcom systéme môžete podľa ID požiadavky, čísla behu a čísla správy priradiť udalosť k správnemu záznamu a spustiť ďalší postup.

JSON notifikácia doMail s identifikáciou požiadavky, behu, adresáta a stavom odosielania správy.
Príklad notifikácie pri odosielaní správy cez ActiveMQ.

Reportovanie nedoručených správ pomocou scenára

Najprv vytvorte skript na reportovanie. Okrem nastavení potrebných na odoslanie e-mailu doň pridajte tento plugin:

reportUndelivered.sendEmail();
Anglické rozhranie editora skriptu s volaním reportUndelivered.sendEmail().
Skript s volaním na vytvorenie e-mailového reportu.

Potom v časti Konfigurácia → Scenáre vytvorte reportovací scenár a priraďte mu pripravený skript. Scenár najprv uložte. Po prvom uložení sa sprístupní záložka Konštanty. V konštantách nastavte príjemcov, interval a obsah reportu podľa nasledujúceho prehľadu. Scenár nezabudnite aktivovať a opätovne uložiť.

Nastavte odosielanie a obsah reportu

Na reportovacom scenári sa používajú konštanty s predponou reportUndelivered.. Najprv nastavte, komu sa report odošle a ako často sa má vytvárať:

Požadované konštanty vyberte v ľavej tabuľke a pridajte ich do pravej tabuľky. Tam nastavte vlastné hodnoty a zmeny uložte.

Konštanty reportovacieho scenára: dostupné konštanty vľavo a vybrané konštanty s vlastnými hodnotami vpravo.
Nastavenie konštánt reportovacieho scenára.
KonštantaVýznam
reportUndelivered.recipientsE-mailové adresy príjemcov reportu. Viaceré adresy oddeľte čiarkou.
reportUndelivered.durationInterval odosielania v dňoch. Hodnota 1 znamená denné reportovanie.
reportUndelivered.sendEmptyUrčuje, či sa má report odoslať aj vtedy, keď neobsahuje žiadne záznamy.
reportUndelivered.reportedIContentNázvy polí iContent zo vstupnej požiadavky, ktoré sa majú pridať do CSV. Oddeľte ich čiarkou; môžu obsahovať napríklad zákaznícke číslo alebo číslo dokladu.
reportUndelivered.subjectPredmet e-mailu s reportom.
reportUndelivered.text
reportUndelivered.html
Textová a HTML verzia obsahu e-mailu s reportom.
reportUndelivered.fileNameNázov CSV prílohy.

V predmete, obsahu a názve prílohy môžete použiť parametre {date}, {dateTime}, {scenario} a {scenarioId}. Doplnia sa aktuálnym dátumom a časom servera alebo názvom a ID reportovacieho scenára. Názov prílohy navyše podporuje {id}, {runid} a {num} na identifikáciu požiadavky, behu a správy, ktorými vznikol report.

Ak potrebujete report iba na vyžiadanie, interval nenastavujte. Vytvorenie reportu môžete spustiť odoslaním požiadavky na reportovací scenár; takto ho môžete vyžiadať aj medzi pravidelnými reportmi. Spracujú sa záznamy označené na reportovanie, ktoré ešte neboli zahrnuté do reportu.

Vyberte scenáre, ktoré chcete sledovať

Na každom scenári, z ktorého chcete dostávať reporty o nedoručení, otvorte Konštanty. V konštante monitorUndelivered.reporting.scenario vyberte pripravený reportovací scenár a zmenu uložte. Samotné vytvorenie reportovacieho scenára ho nepriradí ku všetkým ostatným scenárom.

Alternatívou je priradenie cez monitorUndelivered.reporting.id, kde sa uvádzajú ID reportovacích scenárov oddelené čiarkou. Ak sú reportovacie scenáre určené cez ID, použije sa toto nastavenie pred výberom podľa názvu.

Rovnaký reportovací scenár môžete priradiť viacerým scenárom odosielania. Ak potrebujete rozdielnych príjemcov alebo iný obsah reportu, pripravte samostatné reportovacie scenáre.

Ako čítať dôvod nedoručenia

Správa môže zlyhať pri spracovaní alebo odosielaní. Nedoručenie sa môže zaznamenať aj neskôr, keď po odoslaní príde oznámenie o nedoručení. Report preto môže obsahovať rôzne príčiny, napríklad blokovanie adresy, chybu spracovania alebo odmietnutie správy pri doručovaní.

Podrobnosť vysvetlenia v CSV nastavíte tromi samostatnými konštantami:

  • reportUndelivered.reportReason pridá dôvod vychádzajúci zo stavu spracovania alebo doručenia.
  • reportUndelivered.reportDetail pridá kategorizovaný a lokalizovaný detail nedoručenia, napríklad informáciu o plnej schránke.
  • reportUndelivered.reportOriginal pridá pôvodné znenie chyby vrátane pôvodnej SMTP správy pri chybe doručenia.

Pre bežnú kontrolu pomôže stručný dôvod a detail. Pri technickom riešení problému využijete aj pôvodnú hlášku: vysvetlenie od cieľového servera môže spresniť, či treba opraviť adresu, skontrolovať schránku príjemcu alebo preveriť nastavenie odosielania. Vždy posudzujte celé znenie chyby, pretože samotný číselný kód nemusí vysvetliť konkrétnu príčinu.

Rozdelenie reportov podľa zodpovedných osôb

Okrem spoločného reportu môžete posielať aj čiastkové reporty osobám priradeným ku konkrétnym požiadavkám. Konštanta reportUndelivered.specialRecipients.iContent určuje názov poľa iContent s adresou príjemcu čiastkového reportu. Toto pole zahrňte aj do reportUndelivered.reportedIContent.

Scenár na odoslanie čiastkových reportov nastavíte cez reportUndelivered.reporting.special.scenario alebo reportUndelivered.reporting.special.id. Musí vedieť odoslať report ako prílohu. Takto môže spoločný prehľad dostať prevádzkový tím a jednotlivé prípady príslušná zodpovedná osoba.

Dobre nastavený report pomáha zachytiť nedoručené správy bez každodenného prechádzania jednotlivých komunikácií. Vyberte relevantné scenáre, pridajte údaje potrebné na dohľadanie zákazníka alebo dokladu a určte príjemcov, ktorí môžu na zistené problémy reagovať.