Who is this article for?

Administrators troubleshooting issues with email tracking services.

Administrator permissions are required for some steps.

Email tracking improves productivity and collaboration by showing when and where an email is saved to Microsoft 365.  It's a complex service that relies on several moving parts and Microsoft services.

This article explains how to troubleshoot the email tracking service when something is not working.

1. Common issues

Below is a list of commonly encountered issues and recommended resolutions. If your email tracking service is not working, you need to answer the below questions first:

• Is email tracking not working for everyone? If yes, go to Section 1.1.
• Is email tracking not working for select users only? If yes, go to Section 1.2.. and Section 1.3.

1.1. Client secret has expired

The email tracking service requires a Microsoft client secret to allow this service to work. Microsoft only allows these to be valid for 2 years.

If this client secret has expired, your email tracking service will stop working. If your email tracking was set up 2 years ago, this is most likely your issue.

To check if a secret has expired:

1. Access the Microsoft Entra console.
2. Go to App registrations.
3. Select the OnePlace Email Tracking application.
4. Select Certificates & secrets.
5. Switch to Client secrets.

You will see the expiration date as shown below.

If it is expired, you can update your client secret and apply the new value.

1.2. Email tracking configuration profile not applied to the correct user or group

Email tracking is applied to your users by a configuration profile. This is deployed to specific users or groups and users can only have one configuration profile. We select the configuration profile with the lowest priority number (1 beats 9).

There could be a user who is not in the correct security group, or missed getting the configuration profile applied to them. If this was the case their email tracking would not work.

You can find more information on our article on troubleshooting your configuration profile.

1.3. User is not licensed for email tracking

This is less common; however, some customers have some users licensed for the email tracking service and other users are not.

You can check with your Customer Success Manager or Account manager to double check a specific users email address is licensed for email tracking.

1.4 Gather logs from Microsofts Azure Application insights

Microsoft provides ongoing logs for all email tracking events and errors, you can search and filter these to surface up problems with your email tracking service.

Once you have captured logs you can send these through to Ideagen Mail Manager Enterprise support so we can look for known issues.

Below are the steps to capture common exceptions (errors)

1. In Microsoft's Azure portal, search Application Insights and click on it.
2. click on your production email tracking service:
   
3. Then click on Investigate > Search
4. filter by the date/time range where the issue occurred.

5. Select Event types of "Exception" as shown below, you can also add an additional filter for "Authenticated user" if you know this data.

   

6. You can then copy any exceptions or log data and send this through to Ideagen Mail Manager Enterprise support.

   

   ---

1.5. Troubleshooting Function App crashes on startup.

You can check if the function app (main email tracking component) is running or crashing on the Azure overview page below:

Go to: Azure Portal > search "Function App" > Click into your production Function app > Click the overview page. Then check status. You can also refresh it and restart it.
On the Function App overview page you can also download the app content (include app settings) and attach this to the support ticket, so we can diagnose.

Use Azure Diagnostics:
On the Azure Function App page, you can choose: Diagnose and Solve problems > AI powered diagnostics
Then ask questions relating to your issue.

2. Troubleshooting in Windows PowerShell

2.1. Diagnostic commands

To troubleshoot most issues, you can use the following diagnostic commands in PowerShell.

please note: Powershell experience is required. Anything with v brackets is a <variable> that you need to replace with its name, for example: <Function-app> would be the full name of your function app in Azure.

2.1.1. View app settings

- az functionapp config appsettings list --name <function-app> --resource-group <rg> --output table

2.1.2. Check Service Bus queues

az servicebus queue list --namespace-name <ns> --resource-group <rg> --output table

2.1.3. Check Cosmos DB firewall

az cosmosdb show --name <account> --resource-group <rg> --query "ipRules"

2.1.4. Check partner topic

az eventgrid partner topic show --name <topic> --resource-group <rg> --query "{state:activationState}"

2.1.5. Check app credentials

az ad app credential list --id <AppId> --query "[].{name:displayName, expiry:endDateTime}"

2.1.6. Test health endpoint

Invoke-RestMethod -Uri "https://<app>.azurewebsites.net/api/v1/health" -Headers @{"x-health-check-key" = "<key>"}

Further reading

• Setting up email tracking
• Configuration profiles