Troubleshoot notification delivery

Use this guide when a user reports that they did not receive an expected Brief Connect notification, or when bulk notification delivery appears to have stopped.

This guide covers the standard order of investigation:

Gather information from the reporter.
Confirm the user's notification preferences.
Confirm TeamsAppId is configured.
Check SendNotifications function executions in Application Insights.
Confirm the notification sender mailbox is healthy.
Check the downstream mail service (Exchange Online or SMTP relay such as SendGrid).

Before you start

You need:

Brief Connect System Administrator access (for environment-wide settings such as email templates and default notification settings).
Reader (or higher) access to the Brief Connect Application Insights resource for the affected environment.
The name of the notification sender account for the environment (for example BriefConnect-Admin@<tenant>.onmicrosoft.com).
Access to the tenant's mail service:
Exchange admin role with message trace access, or
Admin access to the SMTP relay (for example SendGrid) if one is configured.

Step 1: Gather information from the reporter

Collect the following before running any queries:

The expected notification type (for example "Record sent to me to action"). See Understanding Brief Connect notifications for the full list.
The record ID that triggered the notification.
The expected recipient(s) (email and user principal name).
Whether the recipient is a direct (named) recipient or a proxy receiving on behalf of another user. Proxies have their own notification preferences and are typically CC'd rather than directly addressed — see Proxy Notifications. If a proxy is affected, also gather the user they proxy for, because both users' preferences and named-user status need to be checked.
The timestamp window of the triggering event (date, time, and time zone). All Application Insights queries are in UTC, so convert the reporter's time to UTC.
The scope of the issue:
One user, one record (likely a preferences or audience issue).
One user, all records (likely a mailbox or proxy issue).
All proxies of one user, or all proxy notifications (likely a proxy preferences issue or expired proxy assignment).
All users (likely a function, mail service, or send-limit issue).

Step 2: Confirm the user's notification preferences

Most "missing notification" reports come from preferences, not delivery failures.

System Administrators cannot view another user's notification preferences. Ask the affected user to check their own settings and share screenshots, or to walk through the checks below with you:

Open notification settings (global and per-record, on the affected record).
Check the Frequency setting. Only All record activity delivers every notification type. Important only and Custom suppress most notifications. See the frequency reference.
If the user expected a proxy notification, confirm that the proxy is active and that the proxy's frequency setting includes the notification type.
Confirm the user is a Named User on the record. Non-named users do not receive notifications even when they have access. The record's role assignments are visible to anyone with access to the record.
Check the user's delivery channel (Email or Teams). A user expecting an email may be set to Teams only.

If the preferences explain the missing notification, no further investigation is needed.

Step 3: Confirm core notification app settings

Several Function App / Web App settings can stop notifications outright or cause systemic failures. Check all of them before moving on to the function logs in Step 4.

Open the Function App and the API Web App for the environment in the Azure portal, then go to Settings → Environment variables.

`DisableAllNotifications` is not `true`

If DisableAllNotifications is true, SendNotifications exits early and logs the warning Notifications are disabled due to function configuration setting 'DisableAllNotifications'. No notifications are sent through any channel. This setting is intended for maintenance/testing only — confirm it is unset or false.

`EmailNotificationsServiceAccount` is a valid sender

This setting names the account Brief Connect sends email notifications from. It must be a valid email address that the configured mail service is permitted to send from:

Microsoft Graph (default). The address must be a real, licensed Exchange Online mailbox in the tenant. The Brief Connect app registration's Mail.Send permission (and any Application Access Policy) must allow sending from this mailbox. A non-existent mailbox surfaces as Graph 404 MailboxNotEnabled in Step 4; a policy mismatch surfaces as 403.
SMTP relay (for example SendGrid). The address must match a verified sender, authenticated domain, or single-sender record in the relay. Many providers also require SPF, DKIM, or DMARC alignment for the sending domain. Check the relay provider's documentation for what "permitted sender" means for that service.

Cross-check the value against:

The recipient field that proxies and users see in their inbox.
The sender used in Monitoring Exchange Online send limits queries.

`TeamsAppId` is configured

TeamsAppId must be set on both the Function App and the API Web App, even if no users currently receive notifications via Teams. The app setting holds the GUID of the published Brief Connect Teams app and is read every time a Teams notification is built.

If TeamsAppId is missing or empty:

The setting accessor throws on every Teams notification attempt. This produces noise in traces and exceptions.
Because Teams and email notifications are processed in the same SendNotifications execution, an error while building a Teams notification can cause the whole queue message to fail and retry — which can delay or block email delivery to other recipients on the same record event.

Confirm TeamsAppId is present and set to the GUID of the published Brief Connect Teams app (the value generated for <<generate new guid>> in the Teams manifest.json). If it is missing, set it on both apps and restart the Function App instance.

For the full procedure, see Section 7.5 of the Teams Application deployment guide.

Step 4: Check `SendNotifications` function executions

Each notification is processed by the SendNotifications queue-triggered Azure Function. Failed executions are retried by the queue and surface in Application Insights as failed requests, traces, and exceptions.

When running App Insights queries, set the time window using the Time range picker above the query editor in Application Insights (or Logs) — for example, Custom → set the start and end to match the window you gathered in Step 1 (in UTC). The picker also accepts presets such as Last 24 hours.

Find failed executions in the time window

requests
| where operation_Name == "SendNotifications"
| where success == false
| project timestamp, resultCode, duration, operation_Id, cloud_RoleName
| order by timestamp desc

Take note of the operation_Id for any failed execution — you use it to correlate logs and exceptions.

Use the operation_Id from a failed request:

union traces, exceptions
| where operation_Id == "<operation_Id>"
| project timestamp, itemType, message, severityLevel, outerMessage = tostring(outerMessage), problemId = tostring(problemId)
| order by timestamp asc

NotificationSenderService logs the record ID in its error messages, so you can also search by record:

union traces, exceptions
| where message has "Failed to send notification" or outerMessage has "Failed to send notification"
| where message has "<RecordId>" or outerMessage has "<RecordId>"
| project timestamp, itemType, message, outerMessage, operation_Id
| order by timestamp desc

Summarise notification health across the environment

Use this to confirm whether failures are isolated or systemic. Set the time-range picker to Last 24 hours (or wider) before running:

requests
| where operation_Name == "SendNotifications"
| summarize total = count(), failed = countif(success == false) by bin(timestamp, 1h)
| extend failureRate = round(100.0 * failed / total, 2)
| order by timestamp desc

A sustained failure rate above a few percent usually points to a downstream issue (mail service, sender mailbox, or send-limit), not the application.

Common failure signatures

Symptom in `traces` / `exceptions`	Likely cause
`Notifications are disabled due to function configuration setting`	The environment has `DisableAllNotifications` enabled. Disable it.
`No recipients found for email notification`	Audience filtering removed everyone (preferences, muted records, no Named Users).
`Failed to get email template for notification type`	Template missing or renamed in the Email Templates section of the Admin Panel.
Exceptions referencing `TeamsAppId` (empty / not configured)	`TeamsAppId` app setting is missing on the PFA Function App or API Web App. See Step 3.
Microsoft Graph `sendMail` errors (`429`, `403`, `MailboxNotEnabled`)	Sender mailbox issue or Exchange Online send limit. Go to Step 5 and Step 6.

Step 5: Confirm the notification sender mailbox is healthy

If the function reaches Graph but sendMail fails, the sender mailbox is usually the cause.

Confirm the sender account exists and is licensed for Exchange Online.
Confirm the sender mailbox is not blocked, disabled, or in a restricted state.
Confirm the Brief Connect app registration still has the Graph Mail.Send application permission, scoped to the sender mailbox if an Application Access Policy is in use.
Confirm the sender account is not over its rolling 24-hour recipient limit. See Monitoring Exchange Online send limits.
Confirm the sender mailbox has not exceeded its storage quota. Once a mailbox passes the Prohibit Send threshold, Graph sendMail calls fail (typically with a QuotaExceeded error). The sender mailbox accumulates a copy of every notification in Sent Items and grows quickly. See Exchange Online mailbox storage limits for current quotas.

We recommend configuring a Messaging Records Management (MRM) retention policy that purges the notification sender mailbox semi-regularly (for example, delete items in Sent Items older than 30 days). See Set up an archive and deletion policy for mailboxes for the procedure.

The most common Graph errors and what they mean (see Microsoft Graph error responses for the full list):

HTTP status	Meaning
`401`	Authentication failed. Token is missing or invalid.
`403`	Access denied. App permissions or an Application Access Policy block the sender mailbox. Inner-error codes such as `ErrorAccessDenied` or `MailboxNotEnabledForRESTAPI` indicate the sender mailbox is not available to the app.
`404`	The requested resource doesn't exist (for example, the sender user ID is not found).
`429`	Throttled. The app is sending too quickly and should back off; often a precursor to hitting the recipient limit.
`503`	Service temporarily unavailable. The queue will retry — confirm whether it self-resolves.
`507`	Insufficient storage. The sender mailbox has reached its storage quota. Purge old items or raise the quota.

In practice, the exception logged by NotificationSenderService contains the Graph response body, which includes the inner-error code and message. Use those values rather than the HTTP status alone when diagnosing — for example, a 403 with MailboxNotEnabledForRESTAPI points at the sender mailbox or Application Access Policy, whereas a 403 with ErrorMessageSubmissionBlocked points at send-throttling or relay policy.

Step 6: Check the downstream mail service

If SendNotifications is succeeding (Graph returned 2xx) but the user still did not receive the email, the message left Brief Connect and the problem is in mail delivery.

Exchange Online (default)

Run a message trace for the time window from Step 1, scoped to the sender account and recipient:

In the Exchange admin centre, open Mail flow → Message trace.
Set the sender to the Brief Connect notification account.
Set the recipient to the affected user.
Set the date range to cover the triggering event (allow a few minutes either side).
Open each result and check the Status and detailed delivery events.

For programmatic traces (and to detect approaching the 10,000-recipient rolling limit), use the script in Monitoring Exchange Online send limits.

SMTP relay (for example SendGrid)

If the environment is configured to send through an SMTP relay rather than Graph:

Open the relay's activity or message log (in SendGrid, Activity → Email Activity).
Filter by the sender address and the affected recipient for the time window.
Check for Bounced, Blocked, Deferred, or Dropped events.
Check suppression lists (bounces, spam reports, unsubscribes). Recipients on a suppression list will silently not receive mail.
Confirm the relay's daily send quota has not been reached.

Recipient inbox rules

If the mail service shows the message was delivered to the recipient but the user reports they did not see it, ask the user to check their own inbox rules. A rule that targets the Brief Connect sender address or notification subject prefixes can silently move, mark-as-read, forward, or delete notifications.

Ask the user to:

Open Outlook → File → Manage Rules & Alerts (or, in Outlook on the web, Settings → Mail → Rules).
Look for any rule that matches on:
- The Brief Connect sender address (the value of EmailNotificationsServiceAccount).
- Subject prefixes used by Brief Connect notifications (for example Key details changed -, Status changed -, Role allocated -, You have been assigned a task -). See the full list in the notification template reference.
Confirm each matching rule's action — common unintended actions are Move to folder, Delete, Mark as read, or Forward to.
Disable or adjust any rule that is misrouting Brief Connect notifications, then ask the user to test a new notification.

Also check:

Junk Email / Spam folder for the time window.
Focused / Other split — Brief Connect notifications can land in Other if the recipient's Focused inbox training has classified them that way.
Tenant-level mail flow rules in the Exchange admin centre that target the Brief Connect sender or subject prefixes (these affect all users, not just one).

Escalate to Brief Connect support

Escalate when:

SendNotifications failure rate is sustained above the environment's normal baseline.
Failures cannot be attributed to mailbox state, send limits, or preferences.
A template error is reported but the template appears configured correctly.

Include the following with the ticket:

Environment name.
Time window (UTC) of the affected notifications.
One or more operation_Id values from failed executions.
The notification type and record ID.
The output of the requests failure-rate query for the last 24 hours.
Message trace results (if mail delivery was reached).