How to Use Get-MessageTrace in Powershell

Organizations in all industries need to ensure the integrity, security, and timely delivery of online messages and emails to improve productivity and streamline workflow.

However, troubleshooting and optimizing email delivery can turn into a real challenge, especially in larger organizations, if you don't know how to proceed.

Although it is also possible to retrieve incoming and outbound messages via the Exchange Admin Center, we can do this with more control by using the Get-MessageTrace PowerShell cmdlet.

In this guide, we'll explore how to use Get-MessageTrace in PowerShell to ensure efficient email tracing.

What is Get-MessageTrace in PowerShell?

Get-MessageTrace is a PowerShell command used in Microsoft Exchange Online Protection (EOP) and Office 365 environments to retrieve detailed information about the delivery and status of email messages.

This cmdlet is only available in the cloud-based service, which means it can only trace messages as they flow through organizations that use cloud-based infrastructure.

Get-MessageTrace Cmdlet Syntax & Meaning

The syntax of the Get-MessageTrace PowerShell cmdlet is the following:

Depending on the parameters, the cmdlet input and output types will change based on your needs.

Each one of these switches and parameters has a meaning. This is a complete list and breakdown of this cmdlet's full meaning:

• EndDate <DateTime>: Specifies the end date and time for the message trace query, indicating the upper limit for the time range of messages to be included in the results;
• FromIP <String>: Filters messages based on the source IP address from which the emails originated;
• MessageId <MultiValuedProperty>: Allows you to specify one or more message IDs to retrieve details about specific email messages;
• MessageTraceId <Guid>: Specifies the unique identifier (GUID) of a specific message trace. Useful for retrieving details about a particular message trace;
• Page <Int32>: Specifies the page number when retrieving a large set of results. Helps in navigating through the pages of the result set;
• PageSize <Int32>: Sets the number of entries to be displayed on each page of the result set. Useful for controlling the granularity and precision of the output;
• ProbeTag <String>: Filters messages based on the probe tag. A probe tag is associated with messages used for testing or monitoring purposes.
• RecipientAddress <MultiValuedProperty>: Filters messages based on the email addresses of the recipients, useful if you want to generate a report by recipient address;
• SenderAddress <MultiValuedProperty>: Filters messages based on the email addresses of the senders;
• StartDate <DateTime>: Specifies the start date and time for the message trace query, indicating the lower limit for the time range of messages to be included in the results;
• Status <MultiValuedProperty>: Filters messages based on their delivery status, allowing you to focus on messages with specific statuses;
• ToIP <String>: Filters messages based on the destination IP address to which the emails were delivered.

What Can You Use The Get-MessageTrace Command For?

The main usage of the Get-MessageTrace cmdlet is to administer and manage email workflow in organizations.

That being said, there are certain scenarios where using this cmdlet provides administrators with more control over email processes, such as the following:

• Email Delivery Tracking: Use Get-MessageTrace to track the delivery status and path of specific email messages;
• Security Threat Detection: Identify and investigate potential security threats, such as phishing attempts, through the analysis of message traces;
• Compliance and Auditing: Meet compliance requirements by auditing and tracking email communication within the organization using message trace data;
• Email Flow Monitoring: Monitor the overall health of your email system by reviewing message trace data and identifying patterns or anomalies in email traffic;
• Policy Enforcement and Optimization: Enforce email policies and optimize email delivery based on the analysis of message trace data, ensuring compliance and efficient communication.

Prerequisites to Run Get-MessageTrace in PowerShell

Since checking email workflows is a delicate task, it is important to receive sufficient admin permissions before running Get-MessageTrace in PowerShell.

According to Microsoft Resources, these are the prerequisites to comply with before being able to run this command:

• Connect to Exchange Online: Use a valid Microsoft Account with admin credentials to connect to Exchange Online PowerShell. Then, move on to the following step.
• Run the Get-ManagementRole Command: Once you have logged into your Microsoft Account, run the following command: Get-ManagementRole -Cmdlet <Cmdlet>. Replace <Cmdlet> with Get-MessageTrace, and press enter.
• Check the Required Permissions: After running the command, PowerShell will return the list of roles necessary to run Get-MessageTrace. If you need additional roles or permissions, you'll need to contact your organization administrator for further assistance.

How to Use Get-MessageTrace in PowerShell

Now that you know what Get-MessageTrace is for, it's time to learn how to use it.

Before continuing, it is important to mention that the output of this command highly depends on its parameters.

Below, we'll show you how to use Get-MessageTrace to retrieve emails for certain data ranges, allowing you more control over email workflows.

Step 1: Connect to Exchange Online PowerShell

First, it's necessary to connect to Exchange Online PowerShell as an Admin to run the Get-MessageTrace command.

To do so, launch PowerShell on your computer, and run the following command:

You'll be prompted to log in using your Microsoft credentials. Don't forget to replace "[email protected]" with your own organization email for the process to work smoothly.

Step 2: Run Get-MessageTrace to See Recent Message Trace Records

After accessing Exchange Online PowerShell and ensuring you have all the required permissions, it's time to run the Get-MessageTrace cmdlet.

According to Microsoft, running this cmdlet without any parameters will only retrieve data from the last 48 hours.

Therefore, if you just want to see a general output of the most recent messages (regardless of recipient and sender information), run the following cmdlet:

The output of the cmdlet will look like this, depending on your organization's size and the number of emails tracked:

Step 3: Set a Specific Date Range with Message Trace in PowerShell

On the other hand, if you want to perform email tracing for certain dates or for specific addresses, then it'll be necessary to modify the cmdlet a bit more.

Of course, the aforementioned cmdlet could be modified to add more parameters based on the information you want to retrieve.

Let's take a look at the following example:

In this example, the command will return message trace information for emails sent by the user James between July 14 and July 17, 2023.

Remember that, in case you fail to specify a date range, the command will return information from users in the last 48 hours.

Get-MessageTrace Errors, Limitations, & How to Fix Them

Despite being a useful command to retrieve important email information, Get-MessageTrace comes with some limitations that should be previously considered, such as the following:

1. It is not possible to set the start date on Get-Message Trace older than 10 days, meaning it can't trace email data greater than 10 days old. Otherwise, the output will return an error message. If you want to see the processing of email messages greater than ten days old, Microsoft recommends using the Start-HistoricalSearch and Get-HistoricalSearch cmdlets;
2. Running the Get-MessageTrace cmdlet without specific parameters will oftentimes return irrelevant information, as it can cause it to timeout after 1,000 results. To prevent this from happening, make sure to modify the Get-MessageTrace parameters to get a clean output, also referred to as "Get-MessageTrace clean results;"
3. In case the cmdlet is not running properly or returning the expected results, try using smaller StartDate and EndDate intervals, opt for a broader time window, check if you have the necessary permissions to run the command, and ask for further help from your organization administrator.

Summary: How to Obtain Get-MessageTrace Data in PowerShell

The granular control provided by the Get-MessageTrace cmdlet serves as a powerful resource for organization administrators, but before using it, consider the following three key takeaways:

• Get-MessageTrace allows us to trace emails in cloud-based organizations by returning in-detail email information from senders and recipient email addresses as instructed in the command;
• It is advisable to set specific date ranges to retrieve email tracing information. Otherwise, the command's output will return lists of irrelevant information to your query, mainly if you work at a large organization;
• Keep in mind that the Get-MessageTrace cmdlet has some limitations, such as the impossibility of tracking emails older than 10 days, and a maximum return of only 1,000 results.