Playing Traffic Cop – Commands for Working with the Exchange Mail Queues

So far this week, we have talked about how to react when Exchange has given up on a message and returned an NDR. Starting today and continuing the rest of the week, we will be discussing how to step in and be the traffic cop to help direct traffic around congestion, "road construction", and other obstacles before the dreaded NDR event happens. There are a number of tools available in the Exchange environment to help diagnose the problem and restore normal traffic flow. These tools include the queue viewer, protocol logging, connectivity logging, message tracking, etc. This article is going to focus on how to use the queue viewer commands to diagnose mail flow interruptions.

This article is the first in a 3 part series on working directly with the Exchange Mail Queues. In this first part, we will tackle the basic commands. In the second and third parts, we will look at common message delivery scenarios and how these commands can be used to solve the most common mail delivery problems.

Basic Concepts

Here are a few notions that should be understood before diving head first into your Exchange server's console session.

• The queue viewer is referred to here as a set of distinct commands. These tasks are also available through the Exchange management UI, but the UI will not be our primary focus as it typically does not provide the same level of control and/or filtering capabilities.
• A routing solution is a subset of the recipients of a message which are all routed to a single destination (or next hop). These solutions are built during routing and the recipients are partitioned into solutions based on their target domain (the address part after the "@" sign), the routing configuration (connectors, weights, AD sites) and other restrictions.
• Destinations (next hops) are basically of two kinds: Exchange mailbox servers and any SMTP servers. Consequently, delivery queues are of two kinds: "local" – to a mailbox server (note: "local" doesn't have to mean the same machine) and "remote" – to an SMTP server. A distinction between the two categories will be made, when relevant. If not specified, it should be assumed that local and remote delivery queues share a common behavior.
• In the following examples, all strings containing names delimited by "<" and ">" must be replaced with actual values (e.g.: <QueueIdentity>, <server name>)
• This is not intended to be a primer on the exhaustive uses of these commands.

Queue Manipulation Commands

The queue viewer is a simple set of powershell commands which can be used to manipulate queues and messages on a server. The two main "status" commands one needs to master are the get-queue and get-message commands. The get-queue command returns information about existing transport queues and the get-message command provides info about the messages queued by the server. These objects have properties that can help us identify them, such as Identity and Subject for messages and Identity and NextHopDomain for queues. There are also other properties which can help diagnose the state of the object, such as Status, LastError and RetryCount.
There are also other "action" commands that will assist in your task by actually performing work on the various queues. The resume-queue command allows one to resume a suspended queue, while conversely suspend-queue allows for the suspending of a problem queue. The retry-queue command forces the queue to immediately attempt to deliver messages again rather than waiting for the next retry interval.
Lastly, there are "action" commands that will assist you by performing actions on individual messages within a queue rather than the entire queue. The suspend-message command allows one to suspend processing of an individual message within a queue, while allowing processing to continue for all other messages. The resume-message command allows one to resume the processing of a suspended message. The export-message command allows for the saving of an individual message to a file external from the mail queue, which can prove useful in addressing issues where mail content may be triggering problems such as prohibited attachment types, excessive size, etc. Lastly, there is the remove-message command which may be used to delete an individual message.

Common Command Examples

The table below illustrates some common uses of some of the various commands. Beginning tomorrow, we will put these together for more productive work.

Command	Usage	Description
Get-Queue	get-queue –SortOrder:-MessageCount	Return all of the active queues on the server in reverse order of message counts starting with the largest queue
	get-queue –SortOrder:-MessageCount –Results:1 | fl	Get the full details of the longest queue
Get-message	get-message -Queue <QueueIdentity>	Get general message details from a specific queue
	get-message –Queue <QueueIdentity> -Results:10	Only return the top 10 messages from the specified queue
	get-message –Filter:{Queue –eq '<QueueIdentity>' –and Status –eq 'Suspended'}	Returns message details for suspended messages in the specified queue
Retry-Queue	retry-queue <QueueIdentity>	Force an immediate delivery attempt for the specified queue
Suspend-Queue	suspend-queue <QueueIdentity>	Suspend processing of the specified queue
Resume-Queue	resume-queue <QueueIdentity>	Resume processing of the specified queue