Applies to: Exchange Server 2010

Topic Last Modified: 2011-03-19

Use the Get-Message cmdlet to view the details of one or more messages in a queue on a computer that has the Hub Transport server role or the Edge Transport server role installed.

Get-Message [-BookmarkIndex <Int32>] [-BookmarkObject <MessageInfo>] [-Filter <String>] [-IncludeBookmark <$true | $false>] [-IncludeComponentLatencyInfo <SwitchParameter>] [-IncludeRecipientInfo <SwitchParameter>] [-ResultSize <Unlimited>] [-ReturnPageInfo <$true | $false>] [-SearchForward <$true | $false>] [-Server <ServerIdParameter>] [-SortOrder <SortOrderEntry[]>]

Get-Message [-Identity <MessageIdentity>] [-BookmarkIndex <Int32>] [-BookmarkObject <MessageInfo>] [-IncludeBookmark <$true | $false>] [-IncludeComponentLatencyInfo <SwitchParameter>] [-IncludeRecipientInfo <SwitchParameter>] [-ResultSize <Unlimited>] [-ReturnPageInfo <$true | $false>] [-SearchForward <$true | $false>] [-SortOrder <SortOrderEntry[]>]

Get-Message [-BookmarkIndex <Int32>] [-BookmarkObject <MessageInfo>] [-IncludeBookmark <$true | $false>] [-IncludeComponentLatencyInfo <SwitchParameter>] [-IncludeRecipientInfo <SwitchParameter>] [-Queue <QueueIdentity>] [-ResultSize <Unlimited>] [-ReturnPageInfo <$true | $false>] [-SearchForward <$true | $false>] [-SortOrder <SortOrderEntry[]>]

Parameter Required Type Description




The BookmarkIndex parameter specifies the position in the result set where the displayed results start. The value of this parameter is a 1-based index in the total result set. The BookmarkIndex parameter can't be used with the BookmarkObject parameter.




The BookmarkObject parameter specifies the object in the result set where the displayed results start. The BookmarkObject parameter can't be used with the BookmarkIndex parameter.




The Filter parameter requires an expression that specifies the property value criteria for the messages that you want to display. The expression includes a property name followed by a comparison operator and value. The following message properties are valid criteria for the Filter parameter:

  • DateReceived   The date that the message was received.
  • ExpirationTime   The time that a message will expire.
  • FromAddress   The SMTP address of the sender of a message. This value is taken from the MAIL FROM header field in the message envelope.
  • Identity   An integer that represents a particular message and an optional server and queue identity.
  • InternetMessageId   The value of the Message-ID header field. This property is expressed as a GUID followed by the SMTP address of the sending server, as in this example:
  • LastError   A text string of the last error recorded for a message.
  • MessageSourceName   A text string of the name of the component that submitted this message to the queue.
  • Queue   The identity of the queue that holds the message. Enter the queue identity in the form of Server\destination, where destination is a remote domain, Mailbox server, or persistent queue name.
  • RetryCount   The number of times that delivery of a message to a destination was tried.
  • SCL   The spam confidence level (SCL) of the message. Valid SCL entries are integers from 0 through 9. An empty SCL property value indicates that the message hasn't been processed by the Content Filter agent.
  • Size   The size of a message.
  • SourceIP   The IP address of the external server that submitted the message to the Exchange organization.
  • Status   The current message status. Message status options are Active, Retry, Suspended, PendingSuspend, or PendingRemove.
  • Subject   A text string that represents the e-mail subject. The value is taken from the Subject header field.

You can specify multiple filter criteria by using the and comparison operator. Property values that aren't expressed as a single integer must be enclosed in quotation marks (").




The Identity parameter specifies the MessageIdentity integer. This is an integer that represents a particular message and an optional server and queue identity. The syntax for this parameter can be specified as follows:

  • Server\QueueIdentity\MessageIdentity
  • QueueIdentity\MessageIdentity
  • Server\*\MessageIdentity
  • MessageIdentity




The IncludeBookmark parameter specifies whether to include the bookmark object when the query results are displayed. The IncludeBookmark parameter is valid when it's used with the BookmarkObject or BookmarkIndex parameters. If you don't specify a value for the IncludeBookmark parameter, the default value of $true is used.




The IncludeComponentLatencyInfo switch specifies whether the information about component latency is included in the message properties. If you include this switch, the message objects returned will include latency measurements for each Transport component that has contributed to the local server latency for each queued message.




The IncludeRecipientInfo parameter specifies whether to display the message recipients in the Recipients field. If you don't include the IncludeRecipientInfo parameter, the Recipients field is blank.

Storing the results of a Get-Message -IncludeRecipientInfo command in a variable allows you to display additional properties for the message recipients. The following list describes the available recipient properties:

  • Address   The e-mail address of the recipient.
  • Type   The recipient type, which may be External, Mailbox, or Distribution Group. Distribution Group is used when the destination is an expansion server.
  • FinalDestination   The distinguished name (DN) of the object used to route the message. The object could be a connector, a Mailbox server, or an expansion server.
  • Status   The recipient status may be Complete, Ready, or Retry.
  • LastError   The SMTP response after the last delivery attempt or a localized error message if the message is placed in the unreachable queue.

For example, to store the recipient information of a message in the remote delivery queue that has the MessageIdentity value of 1234 to a variable named $x, use the following command.

$x=Get-Message -Identity "\1234" -IncludeRecipientInfo

To display the extended recipient properties that are now stored in the $x variable, use the following command.





The Queue parameter specifies the identity of the queue that contains the messages that you want to display. Enter the queue identity in the form of Server\destination, where destination is a remote domain, Mailbox server, or persistent queue name.




The ResultSize parameter specifies the total number of items to display in the result set. The default ResultSize parameter value is set to 1000. The ResultSize parameter supports an unlimited number of results, but Exchange limits the result set to 250,000.




The ReturnPageInfo parameter is a hidden parameter. Use it to return information about the total number of results and the index of the first object of the current page. The default value is $false.




The SearchForward parameter specifies whether to search forward or backward in the result set. The default value is $true. This value causes the result page to be calculated forward from either the start of the result set or forward from a bookmark if specified.




The Server parameter specifies the name of the server to connect to by using the remote procedure call (RPC) that contains the queues that hold the messages that you want to display. Enter the Server parameter as a host name or a fully qualified domain name (FQDN). If this parameter isn't used, the local server is queried.




The SortOrder parameter specifies an array of message properties used to control the sort order of the result set. Separate each property by using a comma. Prepend a plus sign (+) symbol to the beginning of the property name to display the results in ascending order. Prepend a minus sign (-) symbol to the beginning of the property name to display the results in descending order. If you don't specify a sort order, the result set is displayed in ascending order by MessageIdentity integer.

You can display messages by including the server name as part of the Identity parameter or the Queue parameter or by including the Server parameter with a filter query. The Identity parameter, Queue parameter, and Filter parameter settings are mutually exclusive.

You need to be assigned permissions before you can run this cmdlet. Although all parameters for this cmdlet are listed in this topic, you may not have access to some parameters if they're not included in the permissions assigned to you. To see what permissions you need, see the "Queues" entry in the Transport Permissions topic.

This example displays detailed information about all messages queued on the local server and received from any sender at the domain.

Get-Message -Filter {FromAddress -like "*"} | Format-List

This example lists all messages queued on the local server, received from any sender at the domain, and have an SCL value greater than 3.

Get-Message -Filter {FromAddress -like "*" -and SCL -gt 3}

This example displays all messages queued on the server Server1. The results are sorted first in ascending order by sender address and then in descending order of size.

Get-Message -Server -SortOrder: +FromAddress,-Size