Troubleshooting techniques for solving emailing issues in D365FO

In this article, we will explain how to troubleshoot emailing issues in D365FO. We will focus on troubleshooting issues you might encounter when emailing reports using Docentric Email print destination, or when sending outgoing email messages from Batch email sending status via Docentric email distributor batch.

Docentric emailing capabilities are far more powerful than SSRS’s. The main differences between them, which can also cause emailing issues, are:

You can set up the From field on the Print destination settings form.
You can use multiple email sender accounts to send your emails out from D365FO.

My report failed to be emailed. What now?

Let’s say that you’ve tried to email an report and the emailing has failed. We will assume that the error hasn’t been caused by the To field being empty due to unresolved email tokens (e.g. @@, @Invoice@), or by the To, Cc and Bcc fields containing unresolved Docentric placeholders.

Learn about email token redirections >>
Learn about Docentric placeholders >>

Here we will consider only cases where outgoing email messages have been successfully created but failed to be sent out from D365FO. In this article, we will describe the steps needed to troubleshoot such emailing issues. Let’s begin!

First, check if the From field has been set on the Print destination settings form before emailing the report, then proceed to:
Step #1: The From field has not been set > Resolve it, or
Step #2: The From field has been set/resolved > Verify it.

Afterwards, proceed to:
Step #3: The From field is found in Additional email sender accounts, or
Step #4: From is not found in Additional email sender accounts.

Additionally:
Step #5: What if you are using Email distributor batch to email reports, and
Check Exchange Online Sending Limits.

Before you start

Before we proceed, let’s briefly describe Docentric emailing process in regard to choosing the email provider to be used for sending an outgoing email message. This can be one of Additional email sender account (which always uses Docentric SMTP email provider) or Default email provider (which is Docentric SMTP or D36FO Exchange email provider). Please note that currently Docentric doesn't provide its own implementation for Exchange email provider.

Still, we have this on our roadmap, since D365FO Exchange email provider doesn’t support embedded images and email signing, which is also a feature on the roadmap.

Email history

Furthermore, Email history is fully supported by Docentric SMTP email provider. If you are using Exchange, since Docentric only reuses it in the emailing process, Email history is automatically supported.

Which email provider is used for emailing

The email sender address (the From field of the outgoing email message) actually determines which email provider will be used when emailing an outgoing email message using Docentric.

If the sender email address of an outgoing email message is found in Docentric AX parameters > Emailing > Additional email sender accounts, then the corresponding sender account with Docentric SMTP email provider will be used.

Otherwise, Default email provider configured in built-in Email parameters is used, and this can be either Exchange or SMTP. If SMTP -> Docentric SMTP email provider is used, and if Exchange -> D365FO Exchange email provider is used.

This means that the first thing we need to do, when an email fails to be sent out from D365FO, is to determine the email sender address, i.e. the From field of the outgoing email message. The easiest way to see it is to turn on the Open email before sending option in Docentric Email print destination and run the report (Step #2).

However, to understand the whole process and how the From field is resolved in the case that it hasn’t be configured at all, we recommend starting from the beginning 🙂, which means Step #1.

Step #1: The From field has not been set > Resolve it

The goal of this step is to determine how the empty From field has been resolved during report execution.

If the From field is left empty in Docentric Email print destination settings, then the From field is going to be resolved as the email address of the email sender account of Default email provider.

Which email provider is selected to be the default provider, you can find out by opening the Docentric AX parameters > Emailing form. The same value you can see in the Email parameters form, which you can open from Docentric AX parameters > Emailing, or by navigating to System administration > Setup > Email > Email parameters.

There are two email providers used for emailing reports (and by Email distributor batch): Exchange and SMTP. To determine which one is selected to be the default provider, check the Batch email provider field in Email parameters > Configuration.

Note that this selection is named as Default email provider in Docentric terminology, and the corresponding user account as Default email sender account. This is because Docentric introduced so-called Additional email sender accounts, please see the steps below.

Default email provider is SMTP

If the SMTP provider is selected in Email parameters, this is Default email provider in Docentric terminology. Its email sender account is then configured in Email parameters > SMTP settings.

In this case, the empty From field of your outgoing email has been resolved as the email address stored in the User name field in Email parameters > SMTP settings.

If the User name field is empty or is not a valid email address, which can happen if you are using, for example smpt4dev or Exchange OnPrem (e.g. COMPANY\username), then the From field is resolved as the current user email configured in User options. To troubleshoot this situation proceed to Step #3.

Default email provider is Exchange

If the Exchange provider is selected in Email parameters, this is Default email provider in Docentric terminology. Its email sender account is based on the current user email, which is configured in User options.

In this case, the empty From field of your outgoing email has been resolved as the email address of the user which printed the report, i.e. the current user email that is stored in the Sender email field in User options > Account > Email provider selection.

When you determine how the From field should be resolved, proceed to Step #2.

Step #2: The From field has been set/resolved > Verify it

In this step, you need to verify if the From field of the failing outgoing email message is a valid email address that you wanted to use as a sender address.

No matter if the From field has been set on the Print destination settings form to a static email address, to a Docentric placeholder (e.g. @WORKEREMAIL@), or it has been left empty and then resolved in the report execution pipeline as described in Step #1, we need to view the outgoing email message. Only then we will be able to verify whether the From field contains the expected email sender address.

There are a couple of techniques, which you can use to intercept/view outgoing email messages:

The Open email before sending option in Docentric Email print destination. Learn more >>
The Preview before print option, available in all Docentric print destinations, where you can download the outgoing message from Docentric Viewer. Learn more >>
The Email processing mode can be set for any report in Docentric report setup in order to save the outgoing email messages to Batch email sending status. Learn more >>
Use a fake SMTP server such as smtp4dev. Learn how >>

When you are certain that the From field contains a valid email address that you wanted to use in the first place, proceed to Step #3.

Step #3: The From field is found in Additional email sender accounts

Once the From field is known and resolved as a valid email address, Docentric will search for it in the Docentric AX parameters > Emailing > Additional email sender accounts table by the Sender email column. If such sender account is found, it will be used for emailing.

In other words, if the From field is found in Additional email sender accounts, Default email provider will NOT be used.

Note that Additional email sender accounts contains only SMTP accounts, which can be any account or alias from your tenant but also accounts of a third-party SMTP provider such as SendGrid. Learn more >>

In this step, you need to determine if an Additional email sender account, which is always an SMTP account, has been used for emailing of your failing outgoing email message. If the resulting From field matches any Sender email field from Additional email sender accounts, it has. If not, then Default email provider has been used (SMTP or Exchange). In that case, proceed to Step #4.

Troubleshooting steps

You can test connection and send test emails using accounts from Additional email sender accounts.

Verify Outgoing mail server and SMTP port number.
Verify User name and Password and whether the authentication is required.
Verify Specify if SSL is required.
Test login to Outgoing mail server using configured User name and Password by clicking the Test > Test connection button.
Send a test email using configured User name and Password with Sender email in the From field by clicking the Test > Send test email button.
If you are using an account that requires two-factor authentication, the password has to be the "application password" (e.g. as the password you configured in Outlook).

To verify any SMTP settings, you can also use SMTPer.net, an online SMTP test tool.

Step #4: From is not found in Additional email sender accounts

If the From address in not found in the Additional email sender accounts table, then Default email provider is used to send the outgoing email message. Check the Batch email provider field in Email parameters > Configuration to determine which email provider is the default one. See Step #1 for more details.