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 >>

Here it’s important to distinguish between the situations when the User name field is empty and when it’s not:

  • If User name is entered, then it will be used as a login account to Outgoing mail server. Use this field when Sender email is an alias, or account username is not in the form of an email address.
  • If User name is empty, then Sender email will be used as a login account to Outgoing mail server.
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

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

For verification you can also send test emails using accounts from Additional email sender accounts.

  1. Verify Outgoing mail server and SMTP port number.
  2. If User name is empty, verify Sender email and Password. Send a test email using this account.
  3. If User name is set, verify User name and Password. In this case also verify if you can send a test email with Sender email in the From field.
  4. Verify Specify if SSL is required.
  5. 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).

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.

Default email provider is SMTP

In case that Default email provider is SMTP, then the email sender account, which is configured in Email parameters > SMPT settings, has been used as the login account to Outgoing mail server to send your failing outgoing email.

In this step, you need to check (1) whether Email parameters > SMTP settings are valid, and (2) whether the email sender account (i.e. the email address from the From field of your failing outgoing email message) has been granted the Send As permission for the account configured in Email parameters > SMTP settings in Microsoft 365 admin center.

Troubleshooting steps

  1. Verify Outgoing mail server and SMTP port number.
  2. Verify User name and Password.
  3. Verify Specify if SSL is required.
  4. 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).
You can use SMTPer.net, an online SMTP test tool to verify your SMTP settings.

Additional steps, if the From field differs from the email address stored in the User name field in Email parameters > SMTP settings, which can happen only when the From field has been set on the Print destination settings form:

  1. Verify whether the email sender address entered in the From field (e.g. ordering@docentric.com) has been granted the Send As permission for the account configured in Email parameters > SMTP settings (e.g. test@docentric.com) in Microsoft 365 admin center. See Microsoft documentation for the details.

You can test Send As permissions by using the Send test email button from Docentric AX parameters > Emailing > Default email sender account tab. Open the form and enter the email address from the From field of your failed outgoing email (e.g. ordering@docentric.com), then click Send. If the email fails to be sent, contact your system administrator to make necessary changes in your Microsoft 365 admin center.

 

You can use a fake SMTP server such as smtp4dev, where you don’t have to worry about these settings in your development or UAT environments. Learn how to use smpt4dev >>

Default email provider is Exchange

In case that Default email provider is Exchange, then the email address entered in the From field of your failing outgoing email message is used to log into Exchange mail server. In this step, you need to verify if the sender specified in the From field can log into Exchange.

Just to remind you, as we saw in Step #1, if you leave the From field empty, it gets populated with the email address of the user who initiated printing the report, i.e. the current user email that is stored in the Sender email field in User options > Account > Email provider selection.

So, if the From field contains an email address that D365FO cannot log into Exchange with, you will get the following error: "Exchange server could not be contacted. Security token could not be obtained. Ensure a valid Office 365 license is available for this tenant.".

Troubleshooting steps

  1. Verify whether the sender email address in the From field of the outgoing email message is valid and doesn’t belong to external users. Note that external users (for example, external functional consultants configuring client’s emailing) don’t have Exchange accounts on the primary tenant and their accounts cannot be used as email sender accounts when using Exchange email provider.
  2. If the email address in the From field is not an email of an external user, contact your system administrator to check the account setup in Microsoft 365 admin center.
  3. Check if your D365FO environment (e.g. a developer OneBox) is configured to use Exchange Online; it can happen that your OneBox is not authorized to obtain the security token needed for communication with Exchange Online.

You can experiment with Send test email from the Docentric AX parameters > Emailing > Default email sender account tab, and test sending emails using Exchange simply by changing the From field.

 

Sending test emails

You cannot completely test Docentric email providers by using the built-in Test email functionality, which is located in the Email parameters > Test email tab page. This functionality always populates the From field of test emails with the current user email configured in User options so it doesn’t test all possible scenarios enabled by Docentric.

Instead, you should use Docentric’s Default email sender account from Docentric AX parameters > Emailing to test the emailing using Default email provider, and Docentric’s Additional email sender accounts from Docentric AX parameters > Emailing to test the emailing using an additional SMTP email provider.

 

Step #5: What if you are using Email distributor batch to email reports

Docentric enables you to use Email processing to email your reports, which means that outgoing email messages will be stored in Batch email sending status instead of sending out from D365FO immediately after they are created. The same outgoing email queue, Batch email sending status, is used for workflow, alert and retail email notifications.

When Email distributor batch runs, it sends all outgoing emails that are in the Waiting status out from D365FO.

In order to use the same emailing rules and advantages brought by Docentric, you need to turn on the Docentric Email distributor batch option in Docentric AX parameters > Emailing, by turning on the Use Docentric email distributor batch checkbox option. You also need to turn on the Enable email sending log checkbox to enable better logging of errors if the emailing fails.

Read more about emailing reports using Email processing >>
Learn about logging errors of Email distributor batch >>

Troubleshooting steps

So, if an outgoing email message fails to be sent by Email distributor batch, first verify if Docentric Email distributor batch and Email sending log in the Docentric AX parameters > Emailing > Email distributor batch tab are turned on.

If these options are OFF, but you already have Email distributor batch up and running in your environment, you will need to stop the batch job, turn the options ON and then start the batch job again.

If the flags are ON, then check the sender email address specified in the From field, which is never empty for messages saved in the Batch email sending status form. You can do that by downloading or showing the email message.

Then proceed to Step #3 or Step #4.

Note that if the From field doesn’t contain the sender email address you’ve expected, you can change it for a particular message, by clicking Edit, or for multiple selected messages, by clicking Update messages.

 
 
 

Exchange Online Sending Limits

No matter if you are using Exchange or SMTP email provider, standard Exchange Online receiving and sending limits apply. So you might occasionally stumble upon the issue related to sending limits, for example when emailing invoices in batch.

Source: Microsoft documentation.

In order to overcome the sending limit of 30 messages per minute, a new feature which enables email throttling is coming soon! Until then, we recommend using Email processing for emailing critical reports such as invoices, where you can resend the failed emails from Batch email sending status.

However, if you need to send out more than 10K emails per day, you will need to use a third-party SMTP provider such as SendGrid, in combination with Docentric Additional email sender accounts. Learn more >>

Leave a Reply

Your email address will not be published. Required fields are marked *

*

Docentric respects your privacy. Learn how your comment data is processed >>

Docentric respects your privacy. Learn how your comment data is processed >>