MessageTrace report

  • Article

The MessageTrace REST URI provides summary information about the processing of email messages that have passed through the Office 365 system for the organization in the last 30 days. This report is typically used with the MessageTraceDetail report to determine why a message wasn't delivered from the user as expected.

Applies to: Office 365

In this article
REST URIs
Fields
Remarks
Examples
Input parameters and report output columns
Compatibility
Corresponding Windows PowerShell cmdlets
Permissions
Data granularity, persistence, and availability

REST URIs

https://reports.office365.com/ecp/reportingwebservice/reporting.svc/MessageTrace[?ODATA options]

Fields

The following fields can be specified in $select, $filter, and $orderby ODATA2 query options. All fields are returned if no $select option is provided.

Name

WCF Type*

EDM Type*

[In/Out]** Description

Example values

Added in service version

EndDate

System.DateTime

Edm.DateTime

[In] This field is used to limit the report period. Use this field in a $filter query option to set the end date and time of the reporting period. If you supply EndDate in the $filter option, you must also supply StartDate. In this report, this field corresponds to the date and time of the last processing step recorded for the message.

Short Date (for example, 03/10/2013) or Date Time with quotes (for example, "03/10/2013 4:55 PM")

2013-V1

FromIP

string

None specified

[In/Out] The IPv4 or IPv6 address that transmitted the message to the Office 365 email system.

192.168.0.205

2013-V1

MessageId

string

None specified

[In/Out] The Internet MessageID header of the message, if one was supplied. This value can also be explicitly null.

If no ID was provided for the message, the report data will show <d:MessageId m:null="true" /> for Atom, and "MessageId":null for JSON

2013-V1

MessageTraceId

System.Guid

Edm.Guid

[In/Out] An identifier used to get the detailed message transfer trace information.

ae4ad8f6-7613-411c-e67e-08cfc740629

2013-V1

Organization

string

None specified

[In/Out] The fully qualified domain name that was processing the email.

example.onmicrosoft.com

2013-V1

Received

System.DateTime

Edm.DateTime

[In/Out] The date and time when the email was received by the Office 365 email system. This corresponds to the Date field of the first message trace detail entry.

2013-01-09T07:32:54Z

2013-V1

RecipientAddress

string

None specified

[In/Out] The SMTP email address of the user that the message was addressed to.

userone@example.onmicrosoft.com

2013-V1

SenderAddress

string

None specified

[In/Out] The SMTP email address of the user the message was purportedly from. Because sender addresses are commonly spoofed in spam email, they are not considered completely reliable.

usertwo@example.onmicrosoft.com

2013-V1

Size

int

Edm.Int64

[In/Out] The size of the message, in bytes.

39405

2013-V1

StartDate

System.DateTime

Edm.DateTime

[In] This field is used to limit the report period. Use this field in a $filter query option to set the start date and time of the reporting period. If you provide a StartDate in the $filter option, you must also specify an EndDate. In this report, this field corresponds to the date and time of the first processing step recorded for the message.

Short Date (for example, 03/10/2013) or Date Time with quotes (for example, "03/10/2013 4:55 PM")

2013-V1

Status

string

None specified

[In/Out] The status of the message in the Office 365 email system. This corresponds to the Detail field of the last processing step recorded for the message.

Delivered

2013-V1

Subject

string

None specified

[In/Out] The subject line of the message, if one was present for the message.

Free M0ney WoN!

2013-V1

ToIP

string

None specified

[In/Out] The IPv4 or IPv6 address that the Office 365 email system sent the message to.

192.168.0.215

2013-V1

*The WCF Type refers to the .NET Framework data type assigned to the field when you create a Windows Communication Foundation (WCF) Service Reference in Visual Studio. The EDM Type refers to the ADO.NET Entity Data Model (EDM) types returned in Atom-formatted reports.

**For information about [In/Out] indicators, see the "Input parameters and report output columns" section.

Remarks

Each entry in the report includes several fields of metadata. For more information see Common metadata returned by the Office 365 Reporting web service.

The Date field indicates when the messages were handled by the Office 365 system, and are reported in the time zone of those servers.

This report provides summary information of messages that passed through the email system, for which more-detailed trace information is available. To obtain that detailed trace information, your application can use the MessageTraceDetail report. It is important that your application provide all of the following information to obtain the detailed trace information. For more information about tracing messages, see How to: Trace email messages in Office 365.

  • MessageTraceId GUID from the MessageTrace report output.

  • RecipientAddress that the message was sent to.

  • SenderAddress that the message came from.

  • StartDate and EndDate that identify the period for which the message was processed.

Using StartDate and EndDate

The StartDate and EndDate fields do not provide useful information in the report results, and are always set to 0001-01-01T00:00:00Z in the report output. They are intended to enable easy restriction of the reporting time window, and provide finer precision than would be available in a "daily" report.

This can be especially helpful, for example, when recording email-based denial-of-service attacks on an hourly basis. When using these fields, you must include both in the $filter option. They are both considered optional, but if you provide one, you have to provide the other. If the StartDate/EndDate pair is not provided in the query, the default reporting time period is the previous two weeks. The "Examples" section later in this topic shows how to use the StartDate and EndDate fields.

In the MessageTrace report, these fields return the times that you passed in the $filter option. The Received field indicates when the message was received by the system. For failed messages, this can span several days.

Examples

The following example demonstrates how to request message-trace information for the previous 48 hours, which is the default time period.

https://reports.office365.com/ecp/reportingwebservice/reporting.svc/MessageTrace?

<?xml version="1.0" encoding="utf-8"?>
<feed xml:base="https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/" 
    xmlns="http://www.w3.org/2005/Atom" 
    xmlns:d="https://schemas.microsoft.com/ado/2007/08/dataservices"
    xmlns:m="https://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
  <id>https://reports.office365.com/ecp/reportingwebservice/reporting.svc/MessageTrace</id>
  <title type="text">MessageTrace</title>
  <updated>2013-02-09T23:10:29Z</updated>
  <link rel="self" title="MessageTrace" href="MessageTrace" />
  <entry>
    <id>https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MessageTrace(0)</id>
    <category term="TenantReporting.MessageTrace" 
      scheme="https://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" title="MessageTrace" href="MessageTrace(0)" />
    <title />
    <updated>2013-02-09T23:10:29Z</updated>
    <author>
      <name />
    </author>
    <content type="application/xml">
      <m:properties>
        <d:Organization>example.onmicrosoft.com</d:Organization>
        <d:MessageId>&lt;8CFD41EEA339B87-1048-248A6@servername.organization.example.com&gt;</d:MessageId>
        <d:Received m:type="Edm.DateTime">2013-02-08T14:22:55.2046427</d:Received>
        <d:SenderAddress>useone@example.com</d:SenderAddress>
        <d:RecipientAddress>usertwo@example.onmicrosoft.com</d:RecipientAddress>
        <d:Subject>Test Inbound Eicar 20130208 - 922AM</d:Subject>
        <d:Status>Failed</d:Status>
        <d:ToIP m:null="true" />
        <d:FromIP>192.168.0.1</d:FromIP>
        <d:Size m:type="Edm.Int32">3584</d:Size>
        <d:MessageTraceId m:type="Edm.Guid">4682e74e-a81a-4760-c35b-08cfd41eebc2</d:MessageTraceId>
        <d:StartDate m:type="Edm.DateTime">2013-02-07T23:10:28.6473929Z</d:StartDate>
        <d:EndDate m:type="Edm.DateTime">2013-02-09T23:10:28.6473929Z</d:EndDate>
        <d:Index m:type="Edm.Int32">0</d:Index>
      </m:properties>
    </content>
  </entry>
</feed>

Input parameters and report output columns

The [In/Out] indicators in the fields table have the following meanings:

  • Fields marked [In] in the fields table are primarily intended for use in $filter=, $orderby=, and other query options that restrict which entries the report returns. Fields marked [In] in the fields table can be included in the $select= option, and they will appear in the report entries, but they will contain no useful data.

  • Fields marked [In/Out] in the fields table can be used in both the column selection ($select=) and entry restriction ($filter= and $orderby=) options. When you include one of these fields in the $select= option, it will appear in the report entries, and will contain useful data when it is available.

Compatibility

The MessageTrace report was introduced in Office 365 service version 2013-V1. For more information on versioning, see Versioning in the Office 365 Reporting web service.

Corresponding Windows PowerShell cmdlets

The MessageTrace report returns the same information as the Get-MessageTrace Windows PowerShell cmdlet.

Permissions

The account you use to access the reports must have administrative permissions in the Office 365 organization. If the account can view this report in the Office 365 Control Panel, then the account has permissions to retrieve the data from the REST web service. This report requires the user to be assigned to the View-Only Recipients role. In the default Office 365 permissions structure, users with the following administrator permissions can access this report: billing administrator, global administrator, password administrator, service administrator, and user management administrator. For more information, see MailboxUsage report.

Data granularity, persistence, and availability

Information available in this report contains the exact date and time for each event. You can use any feasible time period and duration by including the StartDate and EndDate fields in the $filter option. Times are reported in the time zone of the server scanning the email.

The information for this report is available for a period of 30 days, or until the subscription is canceled.

Events may be delayed by up to 24 hours before they appear in a report.