Export (0) Print
Expand All

How to: Trace email messages in Office 365

The Office 365 Reporting web service  MessageTrace and MessageTraceDetail reports can help administrators troubleshoot mail delivery problems. This topic describes how to call the MessageTrace report to retrieve delivery summary information about recent messages, and how to use those results to obtain detailed processing information about a specific message.

Last modified: February 28, 2013

Applies to: Office 365

In this article
Message tracing data longevity
Using the MessageTrace report
Using the MessageTraceDetail report

Email messages passing through the Office 365 systems generate a significant amount of data, often more information than is in a typical "Check out this site" email. Because of the scale Office 365 operates at, the data isn't retained for the typical one year. The MessageTrace report provides disposition information, indicating what the last action on the message was. The MessageTraceDetail report indicates the detailed processing steps performed on the message. This message trace data is available for the previous 30 days.

The MessageTrace report retrieves a reverse-chronological list of messages that had at least one processing step during the indicated report period. The maximum entries returned by any report is 2000. The following example shows how to retrieve the list of messages processed on January 25, 2013 between noon and 1pm. Line-breaks were added to the request for easier reading.

https://reports.office365.com/ecp/reportingwebservice/reporting.svc/MessageTrace?
  $select=MessageTraceId,RecipientAddress,SenderAddress&
  $filter=StartDate%20eq%20datetime'2013-01-25T12:00:00'%20and%20EndDate%20eq%20datetime'2013-01-25T13:00:00'&
  $format=Atom

The following shows the report results. The fields that are selected in the above request are the ones required to retrieve the detailed information.

<?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="http://schemas.microsoft.com/ado/2007/08/dataservices"
  xmlns:m="http://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-12T02:53: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="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" title="MessageTrace" href="MessageTrace(0)" />
    <title />
    <updated>2013-02-12T02:53:29Z</updated>
    <author>
      <name />
    </author>
    <content type="application/xml">
      <m:properties>
        <d:SenderAddress>userone@example.onmicrosoft.com</d:SenderAddress>
        <d:RecipientAddress>usertwo@example.onmicrosoft.com</d:RecipientAddress>
        <d:MessageTraceId m:type="Edm.Guid">b7a07554-b284-4982-5611-08cfc90c7d16</d:MessageTraceId>
      </m:properties>
    </content>
  </entry>
  <entry>
    <id>https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MessageTrace(1)</id>
    <category term="TenantReporting.MessageTrace" 
      scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" title="MessageTrace" href="MessageTrace(1)" />
    <title />
    <updated>2013-02-12T02:53:29Z</updated>
    <author>
      <name />
    </author>
    <content type="application/xml">
      <m:properties>
        <d:SenderAddress>userone@example.onmicrosoft.com</d:SenderAddress>
        <d:RecipientAddress>usertwo@example.onmicrosoft.com</d:RecipientAddress>
        <d:MessageTraceId m:type="Edm.Guid">3997417a-201b-4a23-bed6-08cfc90c61be</d:MessageTraceId>
      </m:properties>
    </content>
  </entry>
  <entry>
    <id>https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MessageTrace(2)</id>
    <category term="TenantReporting.MessageTrace" 
      scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" title="MessageTrace" href="MessageTrace(2)" />
    <title />
    <updated>2013-02-12T02:53:29Z</updated>
    <author>
      <name />
    </author>
    <content type="application/xml">
      <m:properties>
        <d:SenderAddress>userone@example.onmicrosoft.com</d:SenderAddress>
        <d:RecipientAddress>userthee@example.onmicrosoft.com</d:RecipientAddress>
        <d:MessageTraceId m:type="Edm.Guid">acaa4743-92e8-4e92-b122-08cfc90c4680</d:MessageTraceId>
      </m:properties>
    </content>
  </entry>
  <entry>
    <id>https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MessageTrace(3)</id>
    <category term="TenantReporting.MessageTrace" 
      scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" title="MessageTrace" href="MessageTrace(3)" />
    <title />
    <updated>2013-02-12T02:53:29Z</updated>
    <author>
      <name />
    </author>
    <content type="application/xml">
      <m:properties>
        <d:SenderAddress>userone@example.onmicrosoft.com</d:SenderAddress>
        <d:RecipientAddress>usertwo@example.onmicrosoft.com</d:RecipientAddress>
        <d:MessageTraceId m:type="Edm.Guid">8a1cec20-1ab5-43aa-7ff6-08cfc90c20ca</d:MessageTraceId>
      </m:properties>
    </content>
  </entry>
</feed>

The detailed information available in the MessageTraceDetail report assists the administrator to troubleshooting mailflow problems, and to more-conclusively determine what happened to a message. Because of the potentially large amount of data an unbounded report could generate, the MessageTraceDetail report requires much more restrictive filter options than do the other reports. The following information must be supplied in every MessageTraceDetail request:

  • MessageTraceId GUID from the MessageTrace report output.

  • RecipientAddress that the message was sent to.

  • SenderAddress that the message came from.

  • StartDate and EndDate that encompasses when the message was processed.

In the following example, userthree is trying to find out what why they didn’t receive userone's message from lunchtime that day. Looking back through the report data above, you can see that there was a message processed during that time. The pertinent information is in the following:

    <content type="application/xml">
      <m:properties>
        <d:SenderAddress>userone@example.onmicrosoft.com</d:SenderAddress>
        <d:RecipientAddress>userthee@example.onmicrosoft.com</d:RecipientAddress>
        <d:MessageTraceId m:type="Edm.Guid">acaa4743-92e8-4e92-b122-08cfc90c4680</d:MessageTraceId>
      </m:properties>
    </content>


Using that information, you can request a MessageTraceDetail report like the following. Specify the same StartDate and EndDate, and include the other required information.

https://reports.office365.com/ecp/reportingwebservice/reporting.svc/MessageTraceDetail?
  $select=Action,Date,Detail,Event,MessageTraceId,Organization&
  $filter=StartDate%20eq%20datetime'2013-01-25T12:00:00'%20and%20
    EndDate%20eq%20datetime'2013-01-25T13:00:00'%20and%20
    SenderAddress%20eq%20'userone@example.onmicrosoft.com'%20and%20
    RecipientAddress%20eq%20'usethree@example.onmicrosoft.com'%20and%20
    MessageTraceId%20eq%20guid'acaa4743-92e8-4e92-b122-08cfc90c4680'&
  $format=Atom

The results from that request indicate that the mail was delivered to userthree's mailbox. In other situations, the report might indicate it was deleted as malware or spam, or that the recipient address wasn't recognized by the recipient's mail system, and so on.

<?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="http://schemas.microsoft.com/ado/2007/08/dataservices" 
  xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
  <id>https://reports.office365.com/ecp/reportingwebservice/reporting.svc/MessageTraceDetail</id>
  <title type="text">MessageTraceDetail</title>
  <updated>2013-02-12T03:16:23Z</updated>
  <link rel="self" title="MessageTraceDetail" href="MessageTraceDetail" />
  <entry>
    <id>https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MessageTraceDetail(0)</id>
    <category term="TenantReporting.MessageTraceDetail" 
      scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" title="MessageTraceDetail" href="MessageTraceDetail(0)" />
    <title />
    <updated>2013-02-12T03:16:23Z</updated>
    <author>
      <name />
    </author>
    <content type="application/xml">
      <m:properties>
        <d:Organization>example.onmicrosoft.com</d:Organization>
        <d:MessageTraceId m:type="Edm.Guid">acaa4743-92e8-4e92-b122-08cfc90c4680</d:MessageTraceId>
        <d:Date m:type="Edm.DateTime">2013-01-25T12:11:44.56</d:Date>
        <d:Event>RECEIVE</d:Event>
        <d:Action m:null="true" />
        <d:Detail>Message received by: BY2SR01MB608</d:Detail>
      </m:properties>
    </content>
  </entry>
  <entry>
    <id>https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MessageTraceDetail(1)</id>
    <category term="TenantReporting.MessageTraceDetail" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" title="MessageTraceDetail" href="MessageTraceDetail(1)" />
    <title />
    <updated>2013-02-12T03:16:23Z</updated>
    <author>
      <name />
    </author>
    <content type="application/xml">
      <m:properties>
        <d:Organization>example.onmicrosoft.com</d:Organization>
        <d:MessageTraceId m:type="Edm.Guid">acaa4743-92e8-4e92-b122-08cfc90c4680</d:MessageTraceId>
        <d:Date m:type="Edm.DateTime">2013-01-25T12:11:49.38</d:Date>
        <d:Event>DELIVER</d:Event>
        <d:Action m:null="true" />
        <d:Detail>The message was successfully delivered.</d:Detail>
      </m:properties>
    </content>
  </entry>
</feed>

Now that you're familiar with using the MessageTrace and MessageTraceDetail reports, you can incorporate this functionality in your own helpdesk and support applications.

Show:
© 2014 Microsoft