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
From Business Central 2023 release wave 1, update 23.2, and later, the following operations are also emitted to telemetry:
- Authentication to an SMTP server succeded/failed
- Connection to an SMTP server succeded/failed
Before you can collect this data, you'll have to set up email. For more information, see Set Up Email in the Business Central application help.
Tip
You can also view failed emails in the Email Outbox page in the Business Central client.
Email sent successfully
Occurs when an email was successfully sent from the client.
General dimensions
| Dimension | Description or value |
|---|---|
| message | Email sent successfully |
| user_Id | The 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
| Dimension | Description or value |
|---|---|
| aadTenantId |
Note Azure Active Directory is now Microsoft Entra ID. Learn more |
| clientType | Specifies the type of client that opened the session, such as Background or Web. For a list of the client types, see ClientType Option Type. |
| companyName | The current company name. |
| environmentName | Specifies the name of the tenant environment. Learn more in Managing Environments. |
| environmentType | Specifies the environment type for the tenant, such as Production or Sandbox. Learn more in Environment Types. |
| alConnector | Specifies the email-provider connector used to send the email. Possible values include:
|
| alEmailMessageID | Specifies the GUID assigned to email, like C7A56676-9F3F-4044-90F0-D7F3196AC366. |
| alObjectId | 8888, which is the ID of the system application codeunit that sends emails. |
| alObjectName | Email Dispatcher, which is the name of the system application codeunit that sends the emails. |
| alObjectType | CodeUnit |
| eventId | AL0000CTV |
Failed to send email
Occurs when an email failed to be sent from the client.
General dimensions
| Dimension | Description or value |
|---|---|
| message | Failed to send email. |
| user_Id | The 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
| Dimension | Description or value |
|---|---|
| aadTenantId |
Note Azure Active Directory is now Microsoft Entra ID. Learn more |
| clientType | Specifies the type of client that opened the session, such as Background or Web. For a list of the client types, see ClientType Option Type. |
| companyName | The current company name. |
| environmentName | Specifies the name of the tenant environment. Learn more in Managing Environments. |
| environmentType | Specifies the environment type for the tenant, such as Production or Sandbox. Learn more in Environment Types. |
| alConnector | Specifies the email-provider connector used to send the email. Possible values include:
|
| alEmailMessageID | Specifies the GUID assigned to email, like C7A56676-9F3F-4044-90F0-D7F3196AC366. |
| alErrorCallStack | Specifies the AL callstack when the error occurred. This dimension was added in version 19.0. |
| alErrorText | Specifies the AL error message. This dimension was added in version 19.0. |
| alObjectId | 8888, which is the ID of the system application codeunit that sends emails. |
| alObjectName | Email Dispatcher, which is the name of the system application codeunit that sends the emails. |
| alObjectType | CodeUnit |
| eventId | AL0000CTP |
SMTP server authentication
Occurs when the SMTP module is authenticating to an SMTP server.
General dimensions
| Dimension | Description or value |
|---|---|
| message | Authenticated to SMTP server |
| user_Id | The 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
| Dimension | Description or value |
|---|---|
| aadTenantId |
Note Azure Active Directory is now Microsoft Entra ID. Learn more |
| clientType | Specifies the type of client that opened the session, such as Background or Web. For a list of the client types, see ClientType Option Type. |
| companyName | The current company name. |
| environmentName | Specifies the name of the tenant environment. Learn more in Managing Environments. |
| environmentType | Specifies the environment type for the tenant, such as Production or Sandbox. Learn more in Environment Types. |
| eventId | AL0000GKK |
| alAuthenticated | Specifies 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
// Introduced in version 22.3
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 setup 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
| Dimension | Description or value |
|---|---|
| message | Connected to SMTP server |
| user_Id | The 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
| Dimension | Description or value |
|---|---|
| aadTenantId |
Note Azure Active Directory is now Microsoft Entra ID. Learn more |
| clientType | Specifies the type of client that opened the session, such as Background or Web. For a list of the client types, see ClientType Option Type. |
| companyName | The current company name. |
| environmentName | Specifies the name of the tenant environment. Learn more in Managing Environments. |
| environmentType | Specifies the environment type for the tenant, such as Production or Sandbox. Learn more in Environment Types. |
| eventId | AL0000GKJ |
| alConnected | Specifies 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
// Introduced in version 22.3
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 setup alerting on Business Central telemetry, see Alert on Telemetry.
Email sent (using SMTP)
Occurs when the SMTP module is sending an email.
General dimensions
| Dimension | Description or value |
|---|---|
| message | Email sent |
| user_Id | The 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
| Dimension | Description or value |
|---|---|
| aadTenantId |
Note Azure Active Directory is now Microsoft Entra ID. Learn more |
| clientType | Specifies the type of client that opened the session, such as Background or Web. For a list of the client types, see ClientType Option Type. |
| companyName | The current company name. |
| environmentName | Specifies the name of the tenant environment. Learn more in Managing Environments. |
| environmentType | Specifies the environment type for the tenant, such as Production or Sandbox. Learn more in Environment Types. |
| eventId | AL0000GKL |
| alSent | Specifies 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:
// Connected to SMTP server
// Introduced in version 22.3
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 setup 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 setup alerting on Business Central telemetry, see Alert on Telemetry.
Related information
Monitoring and Analyzing Telemetry
Enable Sending Telemetry to Application Insights
Alert on Telemetry