Find queues and messages in queues in the Exchange Management Shell

As in previous versions of Exchange, you can use the Exchange Management Shell in Exchange Server to view information about queues and messages, and use that information to take action on queues and messages. Typically, an active Exchange contains a large number of queues and messages to be delivered, so it's important to understand how to identify the queues or messages that you want to manage.

Note that you can also use Queue Viewer in the Exchange Toolbox to manage queues and messages in queues. However, the queue and message viewing cmdlets in the Exchange Management Shell support more filterable properties and filter options than Queue Viewer. For more information about using Queue Viewer, see Queue Viewer.

Also remember that queues exist on Mailbox servers and Edge Transport servers (the Transport service). For more information about queues and messages in queues, see Queues and messages in queues.

Queue filtering parameters

The following table summarizes the filtering parameters that are available on the queue management cmdlets.

Queue identity

The Identity parameter uses the basic syntax <Server>\ <Queue>. Typically, this value uniquely identifies the queue, so you can't use other filtering parameters with the Identity parameter. The exception is the Get-Queue cmdlet, where you can use the Include and Exclude parameters with the Identity parameter.

The following table explains the Identity parameter syntax on the queue management cmdlets.

Filter parameter on queue cmdlets

You can use the Filter parameter on all of the queue management cmdlets to identify one or more queues based on the properties of the queues. The Filter parameter creates an OPath filter with comparison operators to restrict the command to queues that meet the filter criteria. You can use the logical operator -and to specify multiple conditions for the match. Here's a generic example of the syntax:

Get-Queue -Filter "<Property1> -<ComparisonOperator> '<Value1>' -and <Property2> -<ComparisonOperator> '<Value2>'..."

For a complete list of queue properties you can use with the Filter parameter, see Queue properties.

For a list of comparison operators you can use with the Filter parameter, see the Comparison operators to use when filtering queues or messages section in this topic.

For examples of procedures that use the Filter parameter to view and manage queues, see Procedures for queues.

Include and Exclude parameters on Get-Queue

You can use the Include and Exclude parameters on the Get-Queue cmdlet by themselves, with each othe , or with the other filtering parameters to fine-tune your results. For example, you can:

• Exclude empty queues.

• Exclude queues to external destinations.

• Include queues that have a specific value of DeliveryType.

The Include and Exclude parameters use the following queue properties to filter queues:

Note that you can duplicate the functionality of the Include and Exclude parameters by using the Filter parameter. For example, the following commands produce the same result:

• Get-Queue -Exclude Empty

• Get-Queue -Filter "MessageCount -gt 0"

However, as you can see, the syntax of the Include and Exclude parameters is simpler and easier to remember.

Get-QueueDigest

The Get-QueueDigest cmdlet allows you to view information about some or all of the queues in your organization by using a single command. Specifically, the Get-QueueDigest cmdlet allows you to view information about queues based on their location on servers, in DAGs, in Active Directory sites, or in the whole Active Directory forest.

Note that queues on a subscribed Edge Transport server aren't included in the results. Also, Get-QueueDigest is available on an Edge Transport server, but the results are restricted to local queues on the Edge Transport server.

The following table describes the filtering and sorting parameters that are available on the Get-QueueDigest cmdlet.

This example returns all non-empty external queues on the servers named Mailbox01, Mailbox02, and Mailbox03.

Get-QueueDigest -Server Mailbox01,Mailbox02,Mailbox03 -Include External -Exclude Empty

Message filtering parameters

The following table summarizes the filtering parameters that are available on the message management cmdlets.

Message identity

The Identity parameter on the message management cmdlets uniquely identifies a message in one or more queues, so you can't use any other message filtering parameters. The Identity parameter uses the basic syntax <Server>\<Queue>\<MessageInteger>.

The following table describes the syntax you can use with Identity parameter on the message management cmdlets.

Filter parameter on message cmdlets

You can use the Filter parameter with the Get-Message, Remove-Message, Resume-Message, and Suspend-Message cmdlets to identify one or more messages based on the properties of the messages. The Filter parameter creates an OPath filter with comparison operators to restrict the command to messages that meet the filter criteria. You can use the logical operator -and to specify multiple conditions for the match. Here's a generic example of the syntax:

Get-Message -Filter "<Property1> -<ComparisonOperator> '<Value1>' -and <Property2> -<ComparisonOperator> '<Value2>'..."

For a complete list of message properties you can use with the Filter parameter, see Message properties).

For a list of comparison operators you can use with the Filter parameter, see the Comparison operators to use when filtering queues or messages section in this topic.

For examples of procedures that use the Filter parameter to view and manage messages, see Procedures for messages in queues.

Queue parameter

The Queue parameter is available only on the Get-Message cmdlet. You can use this parameter to get all messages in a specific queue, or all messages from multiple queues by using the wildcard character (*). When you use the Queue parameter, use the queue identity format <Server>\<Queue> as described in the Queue identity section in this topic.

Comparison operators to use when filtering queues or messages

When you create a queue or message filter expression by using the Filter parameter, you need to include an comparison operator for the property value to match. The comparison operators that you can use, and how each operator functions are described in the following table. For all operators, the values compared aren't case sensitive.

You can specify a filter that evaluates multiple expressions by using the logical operator -and. The queues or messages must match all of the filter conditions to be included in the results.

This example displays a list of queues that have a destination to any SMTP domain name that ends in Contoso.com and that currently contain more than 500 messages.

Get-Queue -Filter "Identity -like '*contoso.com*' -and MessageCount -gt 500"

This example displays a list of messages that are sent from any email address in the contoso.com domain that have an SCL value that's greater than 5.

Get-Message -Filter "FromAddress -like '*Contoso.com*' -and SCL -gt 5"

Advanced paging parameters

When you use the Exchange Management Shell to view queues and messages in queues, your query retrieves one page of information at a time. The advanced paging parameters control the size of the results, and the order that the results are displayed in. All advanced paging parameters are optional and can be used with or without other filtering parameters on the Get-Queue and Get-Message cmdlets. If you don't specify any advanced paging parameters, the query returns the results in ascending order of identity.

By default, when you specify a sort order, the Identity property is always included and sorted in ascending order, because the other available queue or message properties aren't unique.

You can use the BookmarkIndex and BookmarkObject parameters to mark a position in the sorted results. If the bookmark object no longer exists when you retrieve the next page of results, the results start with the closest item to the bookmark, which depends on the sort order that you specify.

The advanced paging parameters are described in the following table.

This example shows how to use the advanced paging parameters in a query. The command returns the first 500 messages on the specified server. The results are sorted first in ascending order by sender address, and then in descending order by message size.

Get-Message -Server mailbox01.contoso.com -ResultSize 500 -SortOrder +FromAddress,-Size

This example returns the first 500 messages on the specified server in the specified sort order, sets a bookmark object, excludes the bookmark object from the results, and retrieves the next 500 messages in the same sort order.

1. Run the following command to retrieve the first page of results.

   $Results=Get-Message -Server mailbox01.contoso.com -ResultSize 500 -SortOrder +FromAddress,-Size
   

2. To set the bookmark object, run the following command to save the last element of the first page to a variable.

   $Temp=$Results[$results.length-1]
   

3. To retrieve the next 500 objects on the specified server, and to exclude the bookmark object, run the following command.

   Get-Message -Server mailbox01.contoso.com -BookmarkObject:$Temp -IncludeBookmark $false -ResultSize 500 -SortOrder +FromAddress,-Size