Back to blog

Email reporting in doMail

R. Pipík
R. Pipík
Updated:

For important emails, you also need to know which messages could not be delivered. doMail collects processing, sending and delivery information. You can use it in database reports, receive updates through ActiveMQ or get undelivered messages by email with a CSV attachment. This helps you correct contact details, resolve a technical issue or reach the customer another way.

What doMail reports

Reporting follows the hierarchy request → processing run → individual messages. One request can create several messages. Reprocessing creates another run, so include the run number when interpreting the results.

The sending state describes processing and dispatch. The delivery state adds subsequent information, such as a non-delivery notification, an open recorded through TrackPixel or a click on a tracked link through TrackLink. A sent email can still have an unknown delivery state. When messages within one run have different delivery states, the aggregate run state can be ambiguous.

A request with two processing runs and multiple emails within each run.
Relationship between a request, processing runs and individual emails.

SMTP errors and non-delivery notifications

A failure can be detected during sending or later, when a non-delivery report (NDR, also called a bounce) arrives. doMail evaluates both the code and message text and categorizes causes such as an invalid address, full mailbox, blocked account, oversized message, security policy rejection or network problem.

Enhanced status codes have a format such as 5.1.1. The 4.x.x class indicates a temporary failure and 5.x.x a permanent failure. A code starting with five does not always mean the address does not exist: 5.1.1 indicates a bad destination mailbox address, whereas 5.7.1 indicates rejection due to authorization or policy. The code meanings are defined in RFC 3463.

In received notifications, the same issue can appear with different codes and wording. The table below records examples of messages concerning a nonexistent or unavailable address. These are combinations received from servers; interpret the complete text alongside the code.

Received message containsReceived code
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

This is why a report can include both the categorized detail and the original SMTP message. A security rejection may mention SPF, DKIM, DMARC or sender blocking. A full mailbox or invalid address requires a different response from a sending configuration error.

Database reporting

We can also prepare database reports tailored to your needs.

If you are interested, contact us at domail@domail.io. We will agree on the report content with you and configure the reports on your doMail instance.

ActiveMQ notifications

When another system needs to respond to state changes, doMail can send JSON notifications to ActiveMQ queues. Notifications cover processing and delivery state changes. Early processing events refer to the request's run; individual message events provide details about a specific message and recipient.

ActiveMQ notifications are available by arrangement. If you are interested, contact us at domail@domail.io. We will agree on the integration details with you and configure notifications on your doMail instance.

A notification includes the event time and these main sections:

  • header — request and run IDs, external and system identifiers, scenario and statistical parameters.
  • requestProcessing — processing and delivery states at run level.
  • email — message number, recipient and individual message states, including available SMTP delivery details.

The requestProcessing and email sections depend on the event's level; do not expect both in every notification. The format is described by the notification JSON schema. The receiving system can match the request ID, run number and message number to its records and initiate the appropriate follow-up.

A doMail JSON notification identifying the request, run and recipient, with the message sending state.
Example of an ActiveMQ notification during message sending.

Reporting undelivered messages using a scenario

First, create a reporting script. Alongside the settings needed to send an email, add the following plugin:

reportUndelivered.sendEmail();
English script editor with the reportUndelivered.sendEmail() call.
A script that calls the email reporting plugin.

Then, in Configuration → Scenarios, create a reporting scenario and assign the prepared script. Save the scenario first. After the first save, the constants tab becomes available. Configure recipients, the interval and report content in the constants using the overview below. Remember to activate the scenario and save it again.

Configure report delivery and content

The reporting scenario uses constants with the reportUndelivered. prefix. Start by choosing who receives the report and how often it is created:

Select the required constants in the left table and add them to the right table. Set your custom values there and save the changes.

Reporting scenario constants: available constants on the left and selected constants with custom values on the right.
Configuring the reporting scenario constants.
ConstantMeaning
reportUndelivered.recipientsEmail addresses that receive the report. Separate multiple addresses with commas.
reportUndelivered.durationSending interval in days. A value of 1 means daily reporting.
reportUndelivered.sendEmptyControls whether the report is sent even when it contains no records.
reportUndelivered.reportedIContentNames of request iContent fields to include in the CSV, separated by commas. These can contain a customer number or document number, for example.
reportUndelivered.subjectSubject of the report email.
reportUndelivered.text
reportUndelivered.html
Plain text and HTML versions of the report email content.
reportUndelivered.fileNameName of the CSV attachment.

The subject, content and attachment name support {date}, {dateTime}, {scenario} and {scenarioId}. These are replaced with the current server date and time or the reporting scenario's name and ID. The attachment name also supports {id}, {runid} and {num} to identify the request, processing run and message used to create the report.

If you only need reports on demand, leave the interval unset. Send a request to the reporting scenario to generate a report; you can also do this between scheduled reports. It processes records marked for reporting that have not yet been included in a report.

Choose which scenarios to monitor

Open constants on each scenario whose undelivered messages you want to report. Select the prepared reporting scenario in monitorUndelivered.reporting.scenario and save the change. Creating a reporting scenario does not automatically assign it to every other scenario.

Alternatively, use monitorUndelivered.reporting.id to specify reporting scenario IDs, separated by commas. When reporting scenarios are specified by ID, that setting takes precedence over selection by name.

You can assign the same reporting scenario to several sending scenarios. Prepare separate reporting scenarios when you need different recipients or report content.

Understand the non-delivery reason

A message can fail during processing or sending. Non-delivery can also be recorded later, when a non-delivery notification arrives after sending. A report can therefore contain different causes, such as an address being blocked, a processing error or a message being rejected during delivery.

Three separate constants control how much detail the CSV provides:

  • reportUndelivered.reportReason adds a reason based on the processing or delivery state.
  • reportUndelivered.reportDetail adds a categorized and localized non-delivery detail, such as a full mailbox.
  • reportUndelivered.reportOriginal adds the original error text, including the original SMTP message for a delivery failure.

A brief reason and detail help with routine checks. For technical investigation, the original message can explain whether you need to correct the address, check the recipient's mailbox or review the sending configuration. Consider the complete error text: a numeric code alone may not explain the specific cause.

Send separate reports to the responsible people

Alongside the combined report, you can send subreports to people associated with individual requests. Set reportUndelivered.specialRecipients.iContent to the name of the iContent field containing the subreport recipient's address. Include this field in reportUndelivered.reportedIContent as well.

Choose the scenario that sends subreports using reportUndelivered.reporting.special.scenario or reportUndelivered.reporting.special.id. It must be able to send the report as an attachment. Your operations team can receive the combined overview while the responsible person receives the relevant cases.

A well-configured report helps you catch undelivered messages without checking every communication individually each day. Choose the relevant scenarios, include the details needed to identify the customer or document, and send the report to people who can respond to the issues.