Using the Exchange Management Shell to Manage Queues
Microsoft Exchange Server 2007 will reach end of support on April 11, 2017. To stay supported, you will need to upgrade. For more information, see Resources to help you upgrade your Office 2007 servers and clients.
Applies to: Exchange Server 2007, Exchange Server 2007 SP1, Exchange Server 2007 SP2, Exchange Server 2007 SP3
This topic describes the queue cmdlets in the Exchange Management Shell and explains how to use the cmdlets and parameter sets to create a query, retrieve the results, and perform modifying actions. For more information about the queue tasks and how they can be used for monitoring and troubleshooting, see Managing Queues.
In Microsoft Exchange Server 2007, you can use the Exchange Management Shell to perform management and configuration tasks and to create scripts to automate tasks. You can also use the Exchange Management Shell to view information about queues on a server and the messages that are present in those queues, and to perform management actions on queues and mail items. These operations are useful for troubleshooting mail flow and identifying spam. For more information about how to use the Exchange Management Shell, see Using the Exchange Management Shell.
Managing Queues and Messages
The queue tasks are grouped into two categories: viewing actions and modifying actions. The viewing actions let you display queues and messages that are queued on the server and select how that data is grouped and sorted when it is displayed. The modifying actions are operations that change the status of queues and messages. Both types of tasks access data by connecting to the transport worker process by using remote procedure calls (RPC). For more information about the Exchange 2007 transport process, see Transport Architecture.
By default, the Exchange Management Shell focuses on the local server. You can also connect to a remote server and view the queues and messages on that server by specifying the remote server name as part of the queue identity or by using the Server parameter with a filter. For more information about how to use the Exchange Management Shell to view queues and messages, see How to View Queues and How to View Messages.
Queue Cmdlets
Table 1 lists the cmdlets that are available in the Exchange Management Shell for managing queues and the messages in the queues. For more information about how to use each cmdlet, see the Help topics listed in the For More Information column.
Table 1 Queue cmdlets
| Cmdlet | Usage | For more information |
|---|---|---|
Export-Message |
This cmdlet saves a copy of a message in an administrator-specified file path. |
|
Get-Message |
This cmdlet lets you view the details of the messages that are currently queued for delivery. You can use the Get-Message cmdlet to retrieve a set of messages and then pipe the results to one of the intrusive cmdlets. |
|
Get-Queue |
This cmdlet lets you view the configuration details of the queues that are present on transport servers. You can use the Get-Queue cmdlet to retrieve a set of queues and then pipe the results to one of the intrusive cmdlets. |
|
Remove-Message |
This cmdlet deletes a message from a queue. The administrator can select whether a non-delivery report (NDR) is sent. |
|
Resume-Message |
This cmdlet resumes delivery of a previously suspended message. You can also use the Resume-Message cmdlet to resubmit messages that are in the poison message queue back to the Submission queue for the categorizer to reprocess. |
|
Resume-Queue |
This cmdlet resumes deliveries of messages from a previously suspended queue. |
|
Retry-Queue |
This cmdlet forces a connection attempt for a queue that currently has a status of Retry. This connection attempt overrides the next scheduled retry. You can also use the Retry-Queue cmdlet together with the Resubmit parameter to send messages that are in delivery queues or in the Unreachable queue back to the Submission queue for the categorizer to reprocess. |
|
Suspend-Message |
This cmdlet suspends delivery of a message that is located in a queue on an Exchange 2007 transport server. |
|
Suspend-Queue |
This cmdlet suspends outgoing activities for a queue that is present on an Exchange 2007 transport server. |
Using the Queue Task Parameter Sets
The queue tasks support multiple parameter sets. These parameter sets are as follows: Identity, Queue, and Filter. The Queue parameter set is available only with message commands. The Identity, Queue, and Filter parameter sets cannot be combined in a command. The Server parameter is used only with a filter expression.
You can also use the advanced paging parameters that are available in the Exchange Management Shell in combination with the Identity, Queue, and Filter parameter sets. The advanced paging parameters are used with the Get-Message and Get-Queue cmdlets to control how the result set is sorted and displayed. The advanced paging parameters are described in Table 4 later in this topic.
You must use an Identity, Queue, or Filter parameter set when you are using a command that modifies messages or queues. If you do not provide any parameters, the Get-Message and Get-Queue cmdlets will display every message or queue object that exists on the local server.
If the result set for a queue or message query contains more than 250,000 items, an error occurs, and you will be prompted to apply a filter to reduce the number of results.
Using the Identity Parameter
Use the Identity parameter when the specific message or queue that you want to view or that you will take action against is known. The search by identity is faster than formulating the same query as a filter. The server name can be expressed as a host name or as a fully qualified domain name (FQDN). You can enter the name of a remote server as part of the identity to initiate an RPC connection to that server so that you can query the queues on that server. If you do not use a server name, the local host is implied. When an identity is provided to a modifying action, the object that is identified must be fully defined and unique. If the identity is not explicit, the action will not be performed. If you omit the server part of the identity, the local computer will be assumed.
When you use the Identity parameter as part of a Get-Queue or Get-Message cmdlet, the Identity parameter supports the use of wildcard expressions.
Queue Identity
Persistent queues have unique names and can be specified by name. Delivery queues are assigned a unique database identity. You can use this database identity to specify a queue, or you can use the name of the delivery destination to specify a queue. To perform an operation on a queue by specifying its unique database identity, you must first run the Get-Queue cmdlet. The database identity will be returned in the results. The accepted identity formats for queues are shown in Table 2.
Table 2 Queue identity formats
| Queue identity format | Usage |
|---|---|
Server\QueueJetID (Int64) |
The complete, unique identity for a delivery queue. |
\QueueJetID |
The identity of a queue on the local server. The server name is omitted. Therefore, the local server is implied. |
Server\* |
Any queue on the specified server. |
Server\NextHopDomain |
A queue on the specified server that is holding messages for delivery to a specific remote domain. |
\NextHopDomain |
A queue that is holding messages destined for a specific domain and that is located on the local server. |
Server\Poison |
The poison message queue that is located on the specified server. |
Server\Submission |
The queue that contains items that are waiting to be processed by the categorizer. |
Server\Unreachable |
The queue that contains items that cannot be routed and that is located on the specified server. |
The following code is an example of how to use a queue identity with the Get-Queue cmdlet. This example returns a list of all queues that are holding messages for delivery to Simple Mail Transfer Protocol (SMTP) domain names that end in Contoso.com. This example also formats the result set as a detailed list:
Get-Queue -Identity Server\*Contoso.com | format-list
Message Identity
The identity of a message is an aggregation of the unique database mail item and the queue identity. An identity, in the form of an integer, is assigned to a message when the message enters the queuing JET database, and that integer is appended to the queue identity to create the message identity. To perform an operation on a message by specifying its database identity, you must first run the Get-Message cmdlet. The identity is returned in the results. If you want to connect to a remote server, you can include the server name as part of the message identity. If the server name is omitted, the local server is assumed. A message that is being sent to more than one recipient may be located in multiple queues. You can use a wildcard character to specify that you want to locate the message in every queue to which the message was routed. Table 3 provides examples of a valid message identity.
Table 3 Message identity formats
| Message identity format | Usage |
|---|---|
Server\QueueJetId\MessageJetID |
Full denomination of a message in a queue. |
Server\Poison\MessageJetID |
A message that is in the poison message queue. |
MessageJetID |
All messages that have this JET database identity and are routed to any queue on the local server (one message routed to multiple queues). |
Server\*\MessageJetID |
All messages that have this JET database identity and are routed to any queue on the specified server. |
The following code is an example of how to use a message identity with the Get-Message cmdlet. This example returns a list of all messages that have the specified identity and are located in any queue on the specified server. This example also formats the result set as a detailed list:
Get-message -Identity Server\*\1234 | Format-List
Using the Filter Parameter
Queue tasks support the Filter parameter to let you specify criteria for which queues and messages should be retrieved. The queue and message properties are used as filter criteria. Create a filter to display a limited set of queues or messages. After you locate the queues and messages that you want to monitor, you can view property information for each object. This information is helpful when you troubleshoot mail flow problems.
Use the Filter parameter to supply an expression with logical and relational operators so that only the queue or message objects that meet the filter criteria are displayed. You can use the -and logical operator to specify multiple conditions that the results will match. If you use the -and operator, only objects that match all specified conditions of the expression are displayed. A subset of the properties of a message or a queue is used to specify the filter criteria. When you specify a property, it must be a valid property for the object for which you are querying, and the value to match must be expressed by using the correct syntax. When a property value is expressed as anything other than a single integer, make sure that you enclose the value in quotation marks.
The Server parameter can be included in a command together with the Filter parameter. Use the Server parameter to specify the host name or FQDN of the server that you want to connect to by using RPC in order to query the queues and messages on that server and retrieve a result set.
For more information about the properties that can be used for filtering, the correct syntax for these properties, and the supported operators, see the following topics:
Using the Queue Parameter
The Queue parameter is used only with message commands. Use this parameter to specify the identity of the queue from which messages are retrieved. If a queue is specified, all messages in that queue are retrieved. This lets you retrieve all messages from a particular queue without having to use a filter expression. You can retrieve messages in multiple queues by using a wildcard character. Use the queue identity format from Table 2 when you use the Queue parameter with a message command. The following code example shows how to use the Queue parameter with a Get-Message cmdlet. This example produces a result set that contains only messages that are located on the specified server and are queued for delivery to the SMTP domain Contoso.com:
Get-message -Queue Server\Contoso.com
Using the Advanced Paging Parameters
Depending on current mail flow, queries against queues and messages can return a very large set of objects. You can use the advanced paging parameters to control how query results are retrieved and displayed.
When you use the Exchange Management Shell to view queues and the messages in the queues, your query retrieves one page of information at a time. The advanced paging parameters control the size of the result set and can also be used to sort the results. All advanced paging parameters are optional and can be combined with any one of the parameter sets that can be used with the Get-Queue and Get-Message cmdlets. If you do not specify any advanced paging parameters, the query returns the results in ascending order of identity. By default, when a sort order is specified, the message identity property is always included and is sorted in an ascending order. This is the default ordering relationship. The message identity property is included because the other properties that can be included in a sort order are not unique. By explicitly including the message identity property in the sort order, you can specify that the results display the message identity sorted in descending order.
You can use the BookmarkIndex and BookmarkObject parameters to mark a position in the sorted result set. If the bookmark object no longer exists when the next page of results is retrieved, the default ordering relationship makes sure that the result set starts with the closest object to the bookmark. The closest object depends on the specified sort order.
Table 4 describes the advanced paging parameters.
Table 4 Advanced paging parameters
| Parameter | Description |
|---|---|
BookmarkIndex |
The BookmarkIndex parameter specifies the position in the result set where the displayed results start. The value of the BookmarkIndex parameter is a 1-based index in the total result set. If the value is less than or equal to zero, the first complete page of results is returned. If the value is set to Int.MaxValue, the last complete page of results is returned. |
BookmarkObject |
The BookmarkObject parameter specifies the object in the result set where the displayed results start. If you specify a bookmark object, that object is used as the point to start the search. The rows before or after that object, depending on the value of the SearchForward parameter, are retrieved. You cannot combine the BookmarkObject parameter and the BookmarkIndex parameter in a single query. |
IncludeBookmark |
The IncludeBookmark parameter specifies whether to include the bookmark object in the result set. By default, this value is set to |
ResultSize |
The ResultSize parameter specifies the number of results to display per page. If you don't specify a value, the default result size of 1,000 objects is used. Exchange Server 2007 limits the result set to 250,000. |
ReturnPageInfo |
The ReturnPageInfo parameter is a hidden parameter. It returns information about the total number of results and the index of the first object of the current page. The default value is |
SearchForward |
The SearchForward parameter specifies whether to search forward or backward in the result set. This parameter does not affect the order in which the result set is returned. It determines the direction of search relative to the bookmark index or object. If no bookmark index or object is specified, the SearchForward parameter determines whether the search starts from the first or last object in the result set. The default value for this parameter is |
SortOrder |
The SortOrder parameter specifies an array of message properties that are used to control the sort order of the result set. The sort order properties are specified in descending order of precedence. Each property is separated by a comma and appended with a + symbol to sort in ascending order, or a - symbol to sort in descending order. If an explicit sort order is not specified by using this parameter, the records that match the query are displayed and sorted by the Identity field for the respective object type. The results are always sorted by identity in ascending order when a sort order is not explicitly specified. |
The following code example shows how to use the advanced paging parameters in a query. In this example, the command connects to the specified server and retrieves a result set that contains 500 objects. The results are displayed in a sorted order, first in ascending order by sender address, and then in descending order of message size:
Get-message -Server Exchange.Contoso.com -ResultSize 500 -SortOrder +FromAddress,-Size
If you want to view successive pages, you can set a bookmark for the last object retrieved in a result set and run an additional query. You must use the scripting capabilities of the Exchange Management Shell to perform this procedure.
The following example uses scripting to retrieve the first page of results, sets the bookmark object, excludes the bookmark object from the result set, and then retrieves the next 500 objects on the specified server.
Example: How to Use Scripting to Set a Bookmark Object
Open the Exchange Management Shell and type the following command to retrieve the first page of results:
$Results=Get-message -Server Exchange.Contoso.com -ResultSize 500 -SortOrder +FromAddress,-SizeTo set the bookmark object, type the following command to save the last element of the first page to a variable:
$temp=$results[$results.length-1]To retrieve the next 500 objects on the specified server and to exclude the bookmark object, type the following command:
Get-message -Server Exchange.Contoso.com -BookmarkObject:$temp -IncludeBookmark $False -ResultSize 500 -SortOrder +FromAddress,-Size
For More Information
For more information about the queue management tasks, see Managing Queues.
For more information about how to use the Exchange Management Shell, see Using the Exchange Management Shell.