Sdílet prostřednictvím

MailTraffic report

  • Článek

The MailTraffic REST URI provides summary information about mail traffic to and from the organization. The start and end date/time of the report can be specified in the request, as can the time period for which the data is aggregated.

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/MailTraffic[?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

Action

string

None specified

[In/Out] Description of the action taken on the message, if any. This field may be blank, or null if no action was performed. For information about valid Action values, see MailFilterList report.

SetSpamConfidenceLevel, RejectMessage

2013-V1

AggregateBy

string

None specified

[In] Indicates whether to combine data into report entries covering full days. The only $filter values allowed are Day and Hour. When not supplied, the report aggregates over 1-hour periods. When included in a $select option, this field always returns null. See the "Remarks" section for more information.

Day or Hour

2013-V1

Date

System.DateTime

Edm.DateTime

[In/Out] The date and time the message was detected as being spam.

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

2013-V1

Direction

string

None specified

[In/Out] Specifies whether the mail was being sent into (Inbound) or out from (Outbound) the organization when it was detected as being spam.

Values are restricted to Inbound and Outbound.

2013-V1

Domain

string

Not specified

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

example.onmicrosoft.com

2013-V1

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.

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

2013-V1

EventType

string

None specified

[In/Out] The type of scanning event logged. For information about valid EventType values, see MailFilterList report.

SpamContentFiltered, SpamIPBlock

2013-V1

MessageCount

int

Edm.Int64

[In/Out] The number of messages that fit the categories indicated by the other fields, over the aggregating period.

1254

2013-V1

Organization

string

None specified

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

example.onmicrosoft.com

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.

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

2013-V1

SummarizeBy

string

None specified

[In] The report field specified in the $filter option using this field determines how the report entries are combined to form a summary. See the "Remarks" section for more information. When included in a $select option, this field always returns null.

Action, EventType, Domain, and Direction are the only allowed values that can be used in a $filter option with this field.

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 the [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.

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

Using the AggregateBy field

The MailTraffic report returns summaries of email-associated events in the Office 365 system. Each event is recorded with its Action, Event, Date, Sender, and so on. The data recorded by Office 365 includes the exact date and time of each event. The "detail" reports, such as MailDetailMalware, provide lists of specific events and their exact times. The "traffic" reports, such as MailTraffic, summarize and can provide counts of those events over two durations: hour and day. You specify which duration to use in the $filter query option, as shown in the following example. If no AggregateBy comparison is included in the $filter option, the default Hour is used.

https://reports.office365.com/ecp/reportingwebservice/reporting.svc/MailTraffic?$filter=AggregateBy eq 'Day'

https://reports.office365.com/ecp/reportingwebservice/reporting.svc/MailTraffic?$filter=AggregateBy eq 'Hour'

Using the SummarizeBy field

The SummarizeBy field enables you to "collapse" the report output on a specified field name. For example, let’s say there were 200 inbound, and 100 outbound mails during a single day-long reporting period. If your query includes $filter=AggregateBy eq ‘Day’, the report would return two separate entries for that day: one for inbound mails showing a MessageCount of 200 and a Direction of Inbound, and another entry for outbound mails showing a MessageCount of 100 and a Direction of Outbound. If you also provide the SummarizeBy field in the $filter option, as in SummarizeBy eq ‘Direction’, the report would then include only one entry for that day, with an empty Direction field, and a MessageCount of 300. The Direction field is empty, because the entry summarizes both Direction eq ‘Inbound’ message counts and Direction eq ‘Outbound’ message counts together.

Only the following fields are supported for use with SummarizeBy.

  • Action

  • EventType

  • Direction

  • Domain

Your requests can include more than one of the allowed fields to summarize, as in the following $filter option.

$filter=SummarizeBy eq 'EventType,Action'

If the request uses SummarizeBy on a field, and also includes that field name in the $select option, the field will always be reported with an empty value.

The following request shows how to request the daily summary of email traffic, with just the Date, Direction, and MessageCount fields returned. The results are to be aggregated by day. Line breaks were added to the request for clarity.

https://reports.office365.com/ecp/reportingwebservice/reporting.svc/MailTraffic?
$select=Date,Direction,MessageCount&
$filter=AggregateBy%20eq%20'Day'&
$format=Atom

The following shows the results of the request. To simplify the results, most of the metadata elements have been removed. Note that there are two entries, one with Direction of Inbound, and the other for the same day with a Direction of Outbound.

<?xml version="1.0" encoding="utf-8"?>
<feed xml:base="https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/">
  <id>https://reports.office365.com/ecp/reportingwebservice/reporting.svc/MailTraffic</id>
  <title type="text">MailTraffic</title>
  <entry>
    <content type="application/xml">
      <m:properties>
        <d:Date m:type="Edm.DateTime">2013-01-29T00:00:00</d:Date>
        <d:Direction>Inbound</d:Direction>
        <d:MessageCount m:type="Edm.Int32">7</d:MessageCount>
      </m:properties>
    </content>
  </entry>
  <entry>
    <content type="application/xml">
      <m:properties>
        <d:Date m:type="Edm.DateTime">2013-01-29T00:00:00</d:Date>
        <d:Direction>Outbound</d:Direction>
        <d:MessageCount m:type="Edm.Int32">58</d:MessageCount>
      </m:properties>
    </content>
  </entry>
 </feed>

If you make the same request with the addition of summarizing by Direction, the request becomes the following.

https://reports.office365.com/ecp/reportingwebservice/reporting.svc/MailTraffic?
$select=Date,Direction,MessageCount&
$filter=AggregateBy%20eq%20'Day'%20and%20SummarizeBy%20eq%20'Direction'&
$format=Atom

The response for that same day then collapses, or summarizes, the Direction field. In other words, it combines the counts for all entries that differ only in their Direction field value. The Direction element is returned as empty, indicating that the report entry combines counts for events, ignoring differences in Direction values.

<?xml version="1.0" encoding="utf-8"?>
<feed xml:base="https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/">
  <id>https://reports.office365.com/ecp/reportingwebservice/reporting.svc/MailTraffic</id>
  <title type="text">MailTraffic</title>
  <entry>
    <content type="application/xml">
      <m:properties>
        <d:Date m:type="Edm.DateTime">2013-01-29T00:00:00</d:Date>
        <d:Direction>
        </d:Direction>
        <d:MessageCount m:type="Edm.Int32">65</d:MessageCount>
      </m:properties>
    </content>
  </entry>
 </feed>

Examples

The following example shows how to retrieve a summary of daily messages inbound to the organization for the first week of January, 2013, in Atom XML-based format. For this report, SummarizeBy EventType was used, so the output is a single report entry for all message dispositions. Line breaks were added to both the request and response for clarity.

https://reports.office365.com/ecp/reportingwebservice/reporting.svc/MailTraffic?
$select=MessageCount,%20Date&
$filter=Direction%20eq%20'Inbound'%20and%20AggregateBy%20eq%20'Day'%20and%20
  StartDate%20eq%20datetime'2013-01-01T00:00:00Z'%20and%20
  EndDate%20eq%20datetime'2013-01-08T00:00:00Z'%20and%20
  SummarizeBy%20eq%20'EventType'&
$format=Atom

<?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/MailTraffic</id>
  <title type="text">MailTraffic</title>
  <updated>2013-02-09T02:02:16Z</updated>
  <link rel="self" title="MailTraffic" href="MailTraffic" />
  <entry>
    <id>https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailTraffic(0)</id>
    <category term="TenantReporting.MailTrafficReport" 
      scheme="https://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" title="MailTrafficReport" href="MailTraffic(0)" />
    <title />
    <updated>2013-02-09T02:02:16Z</updated>
    <author>
      <name />
    </author>
    <content type="application/xml">
      <m:properties>
        <d:Date m:type="Edm.DateTime">2013-01-01T00:00:00</d:Date>
        <d:MessageCount m:type="Edm.Int32">100</d:MessageCount>
      </m:properties>
    </content>
  </entry>
  <entry>
    <id>https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailTraffic(1)</id>
    <category term="TenantReporting.MailTrafficReport" 
      scheme="https://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" title="MailTrafficReport" href="MailTraffic(1)" />
    <title />
    <updated>2013-02-09T02:02:16Z</updated>
    <author>
      <name />
    </author>
    <content type="application/xml">
      <m:properties>
        <d:Date m:type="Edm.DateTime">2013-01-02T00:00:00</d:Date>
        <d:MessageCount m:type="Edm.Int32">150</d:MessageCount>
      </m:properties>
    </content>
  </entry>
  <entry>
    <id>https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailTraffic(2)</id>
    <category term="TenantReporting.MailTrafficReport" 
      scheme="https://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" title="MailTrafficReport" href="MailTraffic(2)" />
    <title />
    <updated>2013-02-09T02:02:16Z</updated>
    <author>
      <name />
    </author>
    <content type="application/xml">
      <m:properties>
        <d:Date m:type="Edm.DateTime">2013-01-03T00:00:00</d:Date>
        <d:MessageCount m:type="Edm.Int32">158</d:MessageCount>
      </m:properties>
    </content>
  </entry>
  <entry>
    <id>https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailTraffic(3)</id>
    <category term="TenantReporting.MailTrafficReport" 
      scheme="https://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" title="MailTrafficReport" href="MailTraffic(3)" />
    <title />
    <updated>2013-02-09T02:02:16Z</updated>
    <author>
      <name />
    </author>
    <content type="application/xml">
      <m:properties>
        <d:Date m:type="Edm.DateTime">2013-01-04T00:00:00</d:Date>
        <d:MessageCount m:type="Edm.Int32">178</d:MessageCount>
      </m:properties>
    </content>
  </entry>
  <entry>
    <id>https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailTraffic(4)</id>
    <category term="TenantReporting.MailTrafficReport" 
      scheme="https://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" title="MailTrafficReport" href="MailTraffic(4)" />
    <title />
    <updated>2013-02-09T02:02:16Z</updated>
    <author>
      <name />
    </author>
    <content type="application/xml">
      <m:properties>
        <d:Date m:type="Edm.DateTime">2013-01-05T00:00:00</d:Date>
        <d:MessageCount m:type="Edm.Int32">116</d:MessageCount>
      </m:properties>
    </content>
  </entry>
  <entry>
    <id>https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailTraffic(5)</id>
    <category term="TenantReporting.MailTrafficReport" 
      scheme="https://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" title="MailTrafficReport" href="MailTraffic(5)" />
    <title />
    <updated>2013-02-09T02:02:16Z</updated>
    <author>
      <name />
    </author>
    <content type="application/xml">
      <m:properties>
        <d:Date m:type="Edm.DateTime">2013-01-06T00:00:00</d:Date>
        <d:MessageCount m:type="Edm.Int32">108</d:MessageCount>
      </m:properties>
    </content>
  </entry>
  <entry>
    <id>https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailTraffic(5)</id>
    <category term="TenantReporting.MailTrafficReport" 
      scheme="https://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" title="MailTrafficReport" href="MailTraffic(5)" />
    <title />
    <updated>2013-02-09T02:02:16Z</updated>
    <author>
      <name />
    </author>
    <content type="application/xml">
      <m:properties>
        <d:Date m:type="Edm.DateTime">2013-01-07T00:00:00</d:Date>
        <d:MessageCount m:type="Edm.Int32">45</d:MessageCount>
      </m:properties>
    </content>
  </entry>
</feed>

The following shows the same reporting results in JSON format.

  {
    "d":
      {
        "results":
          [
              {
                "__metadata":
                  {
                    "id":"https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailTraffic(0)",
                    "uri":"https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailTraffic(0)",
                    "type":"TenantReporting.MailTrafficReport"
                  },
                "Date":"\/Date(1356998400000)\/",
                "MessageCount":100
              },
              {
                "__metadata":
                  {
                    "id":"https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailTraffic(1)",
                    "uri":"https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailTraffic(1)",
                    "type":"TenantReporting.MailTrafficReport"
                  },
                "Date":"\/Date(1357084800000)\/",
                "MessageCount":150
              },
              {
                "__metadata":
                  {
                    "id":"https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailTraffic(2)",
                    "uri":"https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailTraffic(2)",
                    "type":"TenantReporting.MailTrafficReport"
                  },
                "Date":"\/Date(1357171200000)\/",
                "MessageCount":158
              },
              {
                "__metadata":
                  {
                    "id":"https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailTraffic(3)",
                    "uri":"https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailTraffic(3)",
                    "type":"TenantReporting.MailTrafficReport"
                  },
                "Date":"\/Date(1357257600000)\/",
                "MessageCount":178
              },
              {
                "__metadata":
                  {
                    "id":"https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailTraffic(4)",
                    "uri":"https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailTraffic(4)",
                    "type":"TenantReporting.MailTrafficReport"
                  },
                "Date":"\/Date(1357344000000)\/",
                "MessageCount":116
              },
              {
                "__metadata":
                  {
                    "id":"https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailTraffic(5)",
                    "uri":"https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailTraffic(5)",
                    "type":"TenantReporting.MailTrafficReport"
                  },
                "Date":"\/Date(1357430400000)\/",
                "MessageCount":108
              },
              {
                "__metadata":
                  {
                    "id":"https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailTraffic(6)",
                    "uri":"https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailTraffic(6)",
                    "type":"TenantReporting.MailTrafficReport"
                  },
                "Date":"\/Date(135751680000)\/",
                "MessageCount":45
              }
          ]
      }
  }

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 MailTraffic 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 MailTraffic report returns the same information as the Get-MailTrafficReport 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 is stored with 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. This report calculates message counts over hours or days, depending on the AggregateBy field.

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

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