Analyze email telemetry

APPLIES TO: Business Central 2020 release wave 2, update 17.2, and later

Email telemetry gathers data about the following operations:

  • An email was sent successfully
  • An attempt to send an email failed

In application versions that include the SMTP telemetry events documented below, the following operations are also emitted to telemetry:

  • Authentication to an SMTP server succeeded or failed
  • Connection to an SMTP server succeeded or failed
  • Sending an email through SMTP succeeded or failed

Before you can collect this data, you'll have to set up email. Learn more in Set Up Email in the Business Central application help.

These events use TelemetryScope::All. The failed-to-send event uses error verbosity (severityLevel 3). The other events use normal verbosity (severityLevel 1), including SMTP events whose result dimension is No.

Tip

You can also view failed emails in the Email Outbox page in the Business Central client.

Email sent successfully

Occurs when the email dispatcher successfully sends an email.

General dimensions

DimensionDescription or value
messageEmail sent
user_IdThe user telemetry ID for the user. From the user card, you can use user_Id to identify the user who triggered this telemetry event. Learn more in Assign a telemetry ID to users.

Custom dimensions

DimensionDescription or value
aadTenantIdSpecifies the Microsoft Entra tenant ID used for Microsoft Entra authentication. For on-premises, if you aren't using Microsoft Entra authentication, this value is common.
clientTypeSpecifies the type of client that opened the session, such as Background or Web. For a list of the client types, see ClientType Option Type.
companyNameThe current company name.
environmentNameSpecifies the name of the tenant environment. Learn more in Managing Environments.
environmentTypeSpecifies the environment type for the tenant, such as Production or Sandbox. Learn more in Environment Types.
alFeatureNameEmailing
alEventNameEmail sent
alObjectId8713, which is the ID of the system application telemetry logger codeunit.
alObjectNameSystem Telemetry Logger, which emits the event on behalf of the email dispatcher.
alObjectTypeCodeUnit
eventIdAL0000CTV

Failed to send email

Occurs when the email dispatcher fails to send an email.

General dimensions

DimensionDescription or value
messageThe error text returned by the failed send operation.
user_IdThe user telemetry ID for the user. From the user card, you can use user_Id to identify the user who triggered this telemetry event. Learn more in Assign a telemetry ID to users.

Custom dimensions

DimensionDescription or value
aadTenantIdSpecifies the Microsoft Entra tenant ID used for Microsoft Entra authentication. For on-premises, if you aren't using Microsoft Entra authentication, this value is common.
clientTypeSpecifies the type of client that opened the session, such as Background or Web. For a list of the client types, see ClientType Option Type.
companyNameThe current company name.
environmentNameSpecifies the name of the tenant environment. Learn more in Managing Environments.
environmentTypeSpecifies the environment type for the tenant, such as Production or Sandbox. Learn more in Environment Types.
alFeatureNameEmailing
alEventNameFailed to send email
alErrorCallStackSpecifies the AL callstack when the error occurred. This dimension was added in version 19.0.
alErrorTextSpecifies the AL error message. This dimension was added in version 19.0.
alObjectId8713, which is the ID of the system application telemetry logger codeunit.
alObjectNameSystem Telemetry Logger, which emits the event on behalf of the email dispatcher.
alObjectTypeCodeUnit
eventIdAL0000CTP

SMTP server authentication

Occurs when the SMTP module is authenticating to an SMTP server.

General dimensions

DimensionDescription or value
messageAuthenticated to SMTP server.
user_IdThe user telemetry ID for the user. From the user card, you can use user_Id to identify the user who triggered this telemetry event. Learn more in Assign a telemetry ID to users.

Custom dimensions

DimensionDescription or value
aadTenantIdSpecifies the Microsoft Entra tenant ID used for Microsoft Entra authentication. For on-premises, if you aren't using Microsoft Entra authentication, this value is common.
clientTypeSpecifies the type of client that opened the session, such as Background or Web. For a list of the client types, see ClientType Option Type.
companyNameThe current company name.
environmentNameSpecifies the name of the tenant environment. Learn more in Managing Environments.
environmentTypeSpecifies the environment type for the tenant, such as Production or Sandbox. Learn more in Environment Types.
eventIdAL0000GKK
alAuthenticatedSpecifies whether authentication succeeded. Possible values are Yes or No.

Sample KQL code

This KQL code can help you get started analyzing SMTP authentication failures:

// Authenticated to SMTP server
traces
| where timestamp > ago(60d) // adjust as needed
| where customDimensions.eventId == 'AL0000GKK'
| where customDimensions.alAuthenticated == 'No'
| project timestamp
, aadTenantId = customDimensions.aadTenantId
, environmentName = customDimensions.environmentName
, environmentType = customDimensions.environmentType
, companyName = customDimensions.companyName
, clientType = customDimensions.clientType

To learn more about how to set up alerting on Business Central telemetry, see Alert on Telemetry.

SMTP server connections

Occurs when the SMTP module is connecting to an SMTP server.

General dimensions

DimensionDescription or value
messageConnected to SMTP server.
user_IdThe user telemetry ID for the user. From the user card, you can use user_Id to identify the user who triggered this telemetry event. Learn more in Assign a telemetry ID to users.

Custom dimensions

DimensionDescription or value
aadTenantIdSpecifies the Microsoft Entra tenant ID used for Microsoft Entra authentication. For on-premises, if you aren't using Microsoft Entra authentication, this value is common.
clientTypeSpecifies the type of client that opened the session, such as Background or Web. For a list of the client types, see ClientType Option Type.
companyNameThe current company name.
environmentNameSpecifies the name of the tenant environment. Learn more in Managing Environments.
environmentTypeSpecifies the environment type for the tenant, such as Production or Sandbox. Learn more in Environment Types.
eventIdAL0000GKJ
alConnectedSpecifies whether connection succeeded. Possible values are Yes or No.

Sample KQL code

This KQL code can help you get started analyzing SMTP connection failures:

// Connected to SMTP server
traces
| where timestamp > ago(60d) // adjust as needed
| where customDimensions.eventId == 'AL0000GKJ'
| where customDimensions.alConnected == 'No'
| project timestamp
, aadTenantId = customDimensions.aadTenantId
, environmentName = customDimensions.environmentName
, environmentType = customDimensions.environmentType
, companyName = customDimensions.companyName
, clientType = customDimensions.clientType

To learn more about how to set up alerting on Business Central telemetry, see Alert on Telemetry.

Email sent (using SMTP)

Occurs when the SMTP module is sending an email.

General dimensions

DimensionDescription or value
messageSent email.
user_IdThe user telemetry ID for the user. From the user card, you can use user_Id to identify the user who triggered this telemetry event. Learn more in Assign a telemetry ID to users.

Custom dimensions

DimensionDescription or value
aadTenantIdSpecifies the Microsoft Entra tenant ID used for Microsoft Entra authentication. For on-premises, if you aren't using Microsoft Entra authentication, this value is common.
clientTypeSpecifies the type of client that opened the session, such as Background or Web. For a list of the client types, see ClientType Option Type.
companyNameThe current company name.
environmentNameSpecifies the name of the tenant environment. Learn more in Managing Environments.
environmentTypeSpecifies the environment type for the tenant, such as Production or Sandbox. Learn more in Environment Types.
eventIdAL0000GKL
alSentSpecifies whether sending the email succeeded. Possible values are Yes or No.

Sample KQL code

This KQL code can help you get started analyzing failures in sending emails:

// Sent email
traces
| where timestamp > ago(60d) // adjust as needed
| where customDimensions.eventId == 'AL0000GKL'
| where customDimensions.alSent == 'No'
| project timestamp
, aadTenantId = customDimensions.aadTenantId
, environmentName = customDimensions.environmentName
, environmentType = customDimensions.environmentType
, companyName = customDimensions.companyName
, clientType = customDimensions.clientType

To learn more about how to set up alerting on Business Central telemetry, see Alert on Telemetry.

Sample KQL code for alerting on SMTP failures

Use this KQL code if you want to set up alerts on SMTP failures, either failures authenticating/connecting to SMTP servers or failures on sending emails.

traces
| where timestamp > ago(1d) // adjust as needed
| where  customDimensions.eventId == 'AL0000CTP'
     or (customDimensions.eventId == 'AL0000GKK' and customDimensions.alAuthenticated == 'No')
     or (customDimensions.eventId == 'AL0000GKJ' and customDimensions.alConnected == 'No')
     or (customDimensions.eventId == 'AL0000GKL' and customDimensions.alSent == 'No')
| extend EventId = customDimensions.eventId
| summarize count() by
  aadTenantId = tostring( customDimensions.aadTenantId )
, environmentName = tostring( customDimensions.environmentName )
, environmentType = tostring( customDimensions.environmentType )
, companyName = tostring( customDimensions.companyName )
, clientType = tostring( customDimensions.clientType )
, ErrorType = case (
  EventId == 'AL0000CTP', 'Other'
, EventId == 'AL0000GKK', 'SMTP authentication'
, EventId == 'AL0000GKJ', 'SMTP connection'
, EventId == 'AL0000GKL', 'SMTP email'
, 'Unknown'
)

To learn more about how to set up alerting on Business Central telemetry, see Alert on Telemetry.

Monitoring and Analyzing Telemetry
Enable Sending Telemetry to Application Insights
Alert on Telemetry