mail-flow-trace

Trace email delivery through Exchange Online using Microsoft Graph and PowerShell fallback.

Updated Aug 27, 2026
One-click install
npx skills add https://github.com/afoxnyc3/chelsea-piers-itops --skill mail-flow-trace
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: mail-flow-trace
Source: https://github.com/afoxnyc3/chelsea-piers-itops/tree/main/plugins/email-triage-m365/skills/mail-flow-trace
Command: npx skills add https://github.com/afoxnyc3/chelsea-piers-itops --skill mail-flow-trace

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

When an email is not delivered, delayed, bounced, or filtered, it’s difficult to determine what actually happened across Exchange Online, routing, spam handling, and quarantine.

Core Features & Use Cases

  • Inbox search verification: Checks the recipient mailbox for matching messages and classifies where they ended up (Inbox, Junk, Deleted Items, or rule-moved folders).
  • Service health correlation: Looks for Microsoft 365 mail-flow service advisories (including incident indicators) to explain systemic delays or failures.
  • Quarantine notification detection: Detects quarantine-related notices and guides you to the dedicated quarantine inspection workflow.
  • PowerShell fallback for full trace: Provides exact Exchange Online PowerShell commands (Get-MessageTrace / Get-MessageTraceDetail) when Graph results are insufficient.

Quick Start

Trace an email by asking: trace mail flow for <sender-address> to <recipient-address> on <date YYYY-MM-DD>.

Frequently Asked Questions about mail-flow-trace

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I trace an email stuck in Exchange Online mail flow?▼

Mail flow trace checks the recipient mailbox via Microsoft Graph and falls back to Exchange PowerShell Get-MessageTrace to identify routing delays, spam filtering, or delivery failures. It reconstructs the email journey to pinpoint exactly where transport stopped.

Why does an email bounce with an NDR in Microsoft 365?▼

An email bounces with an NDR due to transport routing failures, policy blocks, or invalid recipients. A mail flow trace identifies the exact delivery failure point by analyzing Exchange Online service health advisories and detailed message trace logs.

How do I check if an email was quarantined by Defender policies?▼

Check for quarantine by running a mail flow trace that detects quarantine-related notices and classifies message placement across Inbox, Junk, or Deleted Items. It guides you to a dedicated quarantine inspection workflow when filtering policies intercept the message.

Can I use Exchange PowerShell if Microsoft Graph cannot find a delayed email?▼

Yes, you can use Exchange PowerShell as a fallback when Microsoft Graph cannot resolve full transport routing. The trace provides exact Get-MessageTrace and Get-MessageTraceDetail commands to query Exchange Online logs for delayed or missing messages.

What is the best way to troubleshoot missing emails after a mail flow policy update?▼

The best way to troubleshoot missing emails after a policy update is running a post-change validation mail flow trace. It verifies recipient inbox search placement, correlates Microsoft 365 service health advisories, and checks Defender filtering actions to explain the delivery outcome.

Does mail flow trace work for helpdesk troubleshooting of delayed messages?▼

Yes, mail flow trace works for helpdesk troubleshooting of delayed messages by verifying inbox search placement and correlating Microsoft 365 mail-flow service advisories. It identifies whether delays stem from systemic incidents, spam handling, or transport routing issues.