Applies to: Exchange Server 2013

Topic Last Modified: 2013-01-11

Use the Get-Message cmdlet to view the details of one or more messages in queues on Mailbox servers or Edge Transport servers.

Syntax

Get-Message [-Filter <String>] [-Server <ServerIdParameter>] <COMMON PARAMETERS>
Get-Message [-Identity <MessageIdentity>] <COMMON PARAMETERS>
Get-Message [-Queue <QueueIdentity>] <COMMON PARAMETERS>
COMMON PARAMETERS: [-BookmarkIndex <Int32>] [-BookmarkObject <ExtensibleMessageInfo>] [-IncludeBookmark <$true | $false>] [-IncludeComponentLatencyInfo <SwitchParameter>] [-IncludeRecipientInfo <SwitchParameter>] [-ResultSize <Unlimited>] [-ReturnPageInfo <$true | $false>] [-SearchForward <$true | $false>] [-SortOrder <QueueViewerSortOrderEntry[]>]

Examples

EXAMPLE 1

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

Copy Code 
Get-Message -Filter {FromAddress -like "*@contoso.com"} | Format-List

EXAMPLE 2

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

Copy Code 
Get-Message -Filter {FromAddress -like "*@contoso.com" -and SCL -gt 3}

EXAMPLE 3

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

Copy Code 
Get-Message -Server Server01.contoso.com -SortOrder: +FromAddress,-Size

Detailed Description

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 Mail Flow Permissions topic.

Parameters

Parameter Required Type Description

BookmarkIndex

Optional

System.Int32

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.

BookmarkObject

Optional

Microsoft.Exchange.Data.QueueViewer.ExtensibleMessageInfo

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.

Filter

Optional

System.String

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: 67D7543D6103DC4FBEBA6BC7205DACABA61231@exchange.contoso.com.

  • 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 routing destination or delivery group.

  • 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 email 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 (").

Identity

Optional

Microsoft.Exchange.Data.QueueViewer.MessageIdentity

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

IncludeBookmark

Optional

System.Boolean

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.

IncludeComponentLatencyInfo

Optional

System.Management.Automation.SwitchParameter

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.

IncludeRecipientInfo

Optional

System.Management.Automation.SwitchParameter

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 email 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.

  • 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 Contoso.com remote delivery queue that has the MessageIdentity value of 1234 to a variable named $x, use the following command.

Copy Code 
$x=Get-Message -Identity "Contoso.com\1234" -IncludeRecipientInfo

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

Copy Code 
$x.Recipients

Queue

Optional

Microsoft.Exchange.Data.QueueViewer.QueueIdentity

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 routing destination or delivery group.

ResultSize

Optional

Microsoft.Exchange.Data.Unlimited

The ResultSize parameter specifies the maximum number of results to return. If you want to return all requests that match the query, use unlimited for the value of this parameter. The default value is 1000.

ReturnPageInfo

Optional

System.Boolean

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.

SearchForward

Optional

System.Boolean

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.

Server

Optional

Microsoft.Exchange.Configuration.Tasks.ServerIdParameter

The Server parameter specifies the Exchange server on which you want to run this command. You can use any value that uniquely identifies the server. For example:

  • Name

  • FQDN

  • Distinguished name (DN)

  • Exchange Legacy DN

If you don't use the Server parameter, the command is run on the local server.

SortOrder

Optional

Microsoft.Exchange.Data.QueueViewerSortOrderEntry[]

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.

Input Types

To see the input types that this cmdlet accepts, see Cmdlet Input and Output Types. If the Input Type field for a cmdlet is blank, the cmdlet doesn’t accept input data.

Return Types

To see the return types, which are also known as output types, that this cmdlet accepts, see Cmdlet Input and Output Types. If the Output Type field is blank, the cmdlet doesn’t return data.