Reporting: Delivered or Not?

Utility companies (water, electricity, etc.) and banks often need to know whether their clients received email or not, because they need to inform the client of some event or status. If company is not sure client is informed by the email (the cheapest way), they have to fallback to more expensive methods like postal mail. Knowing email was not delivered is on the other hand used to escalate issue and fix it via call center. Informing the client is often time constrained - they need to know about event or status ahead of time. Or client is informed and has specific time frame to respond or to consider matter closed. To complicate matters even more, some companies have multiple email addresses as backup and delivery to one address is sufficient.

Email was not originally designed with modern reliability standards in mind, so knowing delivery status of email can be gray area. For example, lets say email contains tracking pixel and the tracking pixel link was opened. While this may seem that email was successfully delivered, it is also possible that email server/program scanned the email and read the link while recipient do not even have email in its inbox.

On the other hand, when there is an issue with email delivery you may receive "bounce" email also known as "Non-Delivery Report" (NDR). But here too it may not be what it seems. Bounce emails range from "Belivery failed because of this clear reason. Issue is not on your end. We will try again in X hours" to "Delivery failed". Bounce email contains also SMTP code that should make things clear, but this is often not the case.

Here see some of error messages and smtp codes we received that can be grouped in to single category of "Email address is invalid - non existent":

And the list goes on ...

Domail was build on presumptions above, reports and help you to handle this use cases. For this, Domail utilizes hierarchy of request - run - email. Most of time there is one request, one run, and one email. Sometimes there are more emails, and rarely you may need to resend or reprocess request to existing or additional email addresses.

• 1. Collecting information to report

  
  

  To help our users with this mess, we collect and report following categories of informations:

  • A. All changes to the request/email Domail processes. From receiving the request to sending specific emails.
  • B. Successful delivery of the email via track pixel and link redirection (in html formatted emails)
  • C. Failed delivery of the email via bounce emails

  As stated earlier waters are muddy for point B. and C. but there are tricks that can help improve with detection and categorization of these cases. Track pixel and link metadata like "duration since dispatch" are analyzed to filter out false positives. Bounce emails are categorized based on error messages and SMTP codes and many fall to a few categories:

  • Non-existing/invalid email address
  • Full mailbox
  • Account blocked
  • Message too big
  • Message marked as spam - DMARK/DKIN/SPF/blacklist failure
  • Network issue during delivery
  • Message delivered successfully

  Reporting entries are categorized by states reported. The processing state indicates the current status of the email as it moves through the system - from receiving request to dispatching emails. Delivery state confirms whether the email has successfully reached its intended recipient.

  Reported processing statuses are:

  • 2 - RECEIVED - request is received by Domail
  • 3 - COMPLETED - request is processed - emails are ready to be sent (as soon as posible or in preplanned time)
  • 4 - FAILED - there was a processing error, processing stopped
  • 6 - DUPLICATE - for cases where request uses existing external id and duplicity validation is on
  • 8 - PROCESSING - request is being processed now
  • 9 - BLACKLISTED - email address is on blacklist, no email is sent to this address
  • 10 - DISPATCHING - email is being dispatched now
  • 11 - DISPATCHED - emails was dispatched from Domail and on its way via SMTP
  • 12 - DISPATCH ERROR - dispatch from Domail failed because of issue between Domail and direct SMTP server used
  • 13 - CANCELLED - email was cancelled in any stage of processing
  Reported delivery statuses are:
  • 15 - DELIVERY FAILED - delivery failed, confirmed by bounce email
  • 16 - DELIVERY_NONE - email not dispatched yet
  • 17 - DELIVERY_UNKNOWN - no info about delivery
  • 18 - DELIVERY_CONFIRMED - email delivery confirmed via track pixel or other tracked link
  • 20 - DELIVERY_AMBIGUOUS - emails within run have different delivery states

  Reporting granularity is either by email or by run. Initially delivery state is "delivery none" - email is not dispatched yet. With dispatching, email delivery state changes to "delivery unknown". After dispatching when email delivery state is changed, run state is updated:

  • If there is single email within run, run state reflects email state.
  • If all emails have same state, run reflects email state
  • If emails have different delivery states, run state is "delivery ambiguous"

• 2. Database view

  
  

  Clients running Domail on premise have direct access to database. Here possibilities are endless, from table triggers to polling specific table or view. Main tables of interest are:

  • srv_emails - emails for each processing run and communication/request
  • srv_emlreq - communications/requests
  • srv_procrun - processing runs for each communication/request
  • srv_black_list - blacklisted emails
  

  Out of the box we also provide some reporting views already:

  • view_rpt_blacklisted - list of emails blocked by blacklist
  • view_rpt_delivery_failed - list of emails sent where delivery failed
  • srv_procrun - processing runs for each communication/request
  • view_rpt_email_states - list of all emails with processing and delivery state for their newest run
  

• 3. Reporting to MQ

  
  

  Whole life of processing and delivering is reported to ActiveMQ queues. If needed multiple queues can be used. Queue to send notification is configured in application.properties (Currently [2024-06-24] this feature is not configurable in UI). Correct queue is selected based on cc_inst field (also known as instance id) of the request . For example, lets say there are two separete organization units - east and west, using single Domail instance. This two units can differentiate its emails and request by sending different cc_inst field - 'east' and 'west'. In application.properties you can specify:

  • app.mq.notifications.east = QueueNameEast
  • app.mq.notifications.west = QueueNameWest
  Notifications are JSON messages specified by this JSON schema Notifications have three main parts:
  • header - header containing communication id, run id and statistical and categorization fields like group, operation, category, tags, ...
  • requestProcessing - informations about processing run - state, delivery state
  • email - informations about email - address, state, delivery state
  In the early stages of processing is aggregated in run, so emails are not reported. In later stages each email is processed on its own, so run is not reported.
  

• 4. Reporting via email

  
  

  Another reporting option is using reportUndelivered plugin. With this plugin we can set up scenario to report undelivered emails (for any reason) periodically through email with CSV export. First of all we need reporing script - script that would create report as an attachment. The script must contain call to plugin reportUndelivered.sendEmail();

  

  Report is a CSV file, will contain only emails marked for reporting and can be customized by some scenario parameters. The second step is to create reporting scenario - scenario that calls our reporting script. Reporting can be set up with following scenario parameters (all starting with reportUndelivered):

  • reportUndelivered.reportReason - if true, report will contain column with processing or delivery state that is reason of email being not delivered. For example 'Email blocked' if reason was blacklist
  • reportUndelivered.reportDetail - if true, report will contain column with specific error message that was logged or categorized SMTP delivery failure. For example 'Full mailbox!'
  • reportUndelivered.reportOriginal - if true, report will contain column with specific error message that was logged or original SMTP delivery failure. This way you can analyze NDR yourself and not rely on categorization by Domail, or simply check categorization validity.
  • reportUndelivered.reportedIContent - contains a comma separated list of iContent fields from request. If your request specifies this fields they can be referenced by report for easy analysis.
  • reportUndelivered.duration - specifies schedule of reporting in days - 1 means report every day
  • reportUndelivered.sendEmpty - if true report is sent even empty
  • reportUndelivered.recipients - contains comma separated list of recipients to send report to
  • reportUndelivered.subject - contains subject of reporting email
  • reportUndelivered.text - contains text part of reporting email
  • reportUndelivered.html - contains HTML part of reporting email
  • reportUndelivered.fileName - name for created CSV report file.
  Parameters for fileName, text, html and subject can contain placeholders to better identify reports:
  • {date} - date of the report
  • {dateTime} - date and time of report
  • {scenario} - name of reporting scenario
  • {scenarioId} - id of reporting scenario
  • {id} - id of request used for creating report
  • {runid} - id of run used for creating report
  • {num} - number of email used for creating report
  On top of single report email, plugin can create additional special reports sent to persons associated with specific emails. This persons are referenced through iContent field of request. Special report is sent through specified scenario (can be any scenario that will make sure attachment is sent to recipients):
  • reportUndelivered.specialRecipients.iContent - name of iContent field containing additional report recipients for reported email. This field is from reported email request, so each reported email could go to different recipient on top of general report.
  • reportUndelivered.reporting.special.id - id number of scenario that is used to send special report
  • reportUndelivered.reporting.special.scenario - name of scenario that is used to send special report

  Advantage of reporting being implemented as scenario is that it can be used like any other Domail scenario. By standard you set up scenario with values specified above and reporting will run every 'reportUndelivered.duration' days with email containing 'reportUndelivered.subject' subject and 'reportUndelivered.html' content. Do you need report now? Just send request to Domail that indicates this scenario and report will be sent according to request with all emails marked for reporting from last reporting. It is also possible to not schedule reporting at all by not setting 'reportUndelivered.duration', and when you need report just send the request for given scenario.

  The only thing to cover is how does Domail select emails to be reported. Some scenarios are used for more important stuff than other, so reporting is set up only for relevant scenarios. Again we use scenario parameters for this:

  • monitorUndelivered.reporting.id - list of scenario IDs used to report current scenario
  • monitorUndelivered.reporting.scenario - list of scenario names used to report current scenario

  You can specify more than one reporting scenario, to report current scenario multiple times and with different parameters. Also you can use same reporting scenario to report multiple scenarios. With reported scenarios and reporting scenarios being set up, each email associated with reported scenario is marked to be reported when delivery fails for any reason.

With all reporting info after us, we wish you your emails are delivered and your reports are empty.