Share via

MailTrafficSummary reports

  • Article

The MailTrafficSummary REST URI provides a summary list in a variety of categories related to messages processed through the organization's Office 365 email system. 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. This report returns 20 generically-named fields, and the data in these fields can change based on the other options.

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

C1 through C20

usually string

Usually none specified

[In/Out] The meaning of data in this field varies. Refer to the definitions in the "Remarks" section.

userone@example.onmicrosoft.com

2013-V1

Category

string

None specified

[In] The type of summary report requested. The setting of this field in the $filter option determines the meaning of the C1-C20 fields. See the "Remarks" section for more information.

OutboundHits, TopMailSender, TopMalware, and so on

2013-V1

DlpPolicy

string

None specified

[In/Out] The name of the DLP policy that was applied to the message. For information about valid DlpPolicy values, see MailFilterList report.

Financial Data Detection, HIPAA Detection, PII Detection

2013-V1

Domain

string

None 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

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

TransportRule

string

None specified

The name of the Microsoft Exchange transport rule executed in the processing step. For information about valid TransportRule values, see MailFilterList report.

PII Detection

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.

The ODATA $orderby option does not function with this report.

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.

Categories and Cn field definitions

The definition of the generically-named C1 through C20 fields changes based on the value specified for Category. To specify a category, include a matching expression in the $filter option, like in the following example.

$filter=Category eq 'TopMailRecipient'

The following lists the values allowed for the Category field, and the type of information returned.

  • InboundDLPHits returns an ordered list of the number of times the indicated data loss prevention (DLP) policy actions were triggered during the reporting period for inbound messages.

  • InboundDLPPolicyRuleHits returns an ordered list of the number of times the indicated DLP policy rule actions were triggered during the reporting period for inbound messages.

  • InboundTransportRuleHits returns an ordered list of the number of times the indicated Transport rule actions were triggered during the reporting period for inbound messages.

  • OutboundDLPHits returns an ordered list of the number of times the indicated Data Leakage Protection (DLP) policy actions were triggered during the reporting period for outbound messages.

  • OutboundDLPPolicyRuleHits returns an ordered list of the number of times the indicated DLP policy rule actions were triggered during the reporting period for outbound messages.

  • OutboundTransportRuleHits returns an ordered list of the number of times the indicated Transport rule actions were triggered during the reporting period for outbound messages.

  • TopMailSender returns an ordered list of the users who sent the most email during the reporting period.

  • TopMailRecipient returns an ordered list of the users who received the most email during the reporting period.

  • TopMalware returns an ordered list of the malware detected during the reporting period.

  • TopMalwareRecipient returns an ordered list of the users who received the most messages containing malware during the reporting period.

  • TopSpamRecipient returns an ordered list of the users who received the most messages containing spam during the reporting period.

The following table lists the Category value, and the resulting definitions of the Cn fields. Only the columns that contain information are listed in the table. Columns that have no data in the report have a null value. Many of the values returned in the columns also appear in the lists returned by the MailFilterList report. If you use the $filter expression to match specific DLP policies, DLP rules, or Transport rules, use the values returned in the MailFilterList report to ensure accurate matches.

The fields C4-C20 are not currently used, and are reserved for future expansion.

Category

Populated columns

Example

InboundDLPHits

C1: [string] Data loss prevention (DLP) rule name.
C2: [int] Number of times any of the DLP policy actions were triggered in the reporting period.

<d:C1>PII Detection</d:C1>
<d:C2>398</d:C2>

InboundDLPPolicyRuleHits

C1: [string] DLP policy name.
C2: [string] DLP rule name.
C3: [string] Action.
C4: [int] Number of times the action was taken in the reporting period.

<d:C1>PII Detection</d:C1>
<d:C2>PII Detection</d:C2>
<d:C3>SetAuditSeverityMedium</d:C3>
<d:C4>398</d:C4>

InboundTransportRuleHits

C1: [string] Transport rule name.
C2: [string] Action.
C3: [int] Number of times the Transport rule was triggered in the reporting period.

<d:C1>PII Detection</d:C1>
<d:C2>SetAuditSeverityMedium</d:C2>
<d:C3>398</d:C3>

OutboundDLPHits

C1: [string] DLP rule name.
C2: [int] Number of times the rule was triggered in the reporting period.

<d:C1>PII Detection</d:C1>
<d:C2>398</d:C2>

OutboundDLPPolicyRuleHits

C1: [string] DLP policy name.
C2: [string] DLP rule name.
C3: [string] Action.
C4: [int] Number of times the action was taken in the reporting period.

<d:C1>PII Detection</d:C1>
<d:C2>PII Detection</d:C2>
<d:C3>SetAuditSeverityMedium</d:C3>
<d:C4>398</d:C4>

OutboundTransportRuleHits

C1: [string] Transport rule.
C2: [string] Action.
C3: [int] Number of times the Transport rule was triggered in the reporting period.

<d:C1>PII Detection</d:C1>
<d:C2>SetAuditSeverityMedium</d:C2>
<d:C3>398</d:C3>

TopMailSender

C1: [string] SMTP email address of the user who sent the most email during the reporting period.
C2: [int] Number of email messages sent by that user in the reporting period.

<d:C1>userone@example.onmicrosoft.com</C1>
<d:C2>14</C2>

TopMailRecipient

C1: [string] SMTP email address of the user who received the most email during the reporting period.
C2: [int] Number of email messages received by that user in the reporting period.

<d:C1>usertwo@example.onmicrosoft.com</C1>
<d:C2>4752</C2>

TopMalware

C1: [string] Name of the malware received most often during the reporting period.
C2: [int] Number of email messages containing the malware.

<d:C1>dos/eicar_test_file</d:C1>
<d:C2>1</d:C2>

TopMalwareRecipient

C1: [string] SMTP email address of the user who received the most messages carrying malware during the reporting period.
C2: [int] Number of malware-containing email messages received by that user in the reporting period.

<d:C1>usertwo@example.onmicrosoft.com</C1>
<d:C2>2401</C2>

TopSpamRecipient

C1: [string] SMTP email address of the user who received the most messages carrying spam during the reporting period.
C2: [int] Number of spam email messages received by that user in the reporting period.

<d:C1>usertwo@example.onmicrosoft.com</C1>
<d:C2>2350</C2>

Examples

The following example requests the top two email recipients for the last three months of 2012. Line breaks were added to both the request and response for clarity.

https://reports.office365.com/ecp/reportingwebservice/reporting.svc/MailTrafficSummary?
  $select=C1,C2,C3&
  $filter=Category%20eq%20'TopMailRecipient'%20and%20
    StartDate%20eq%20datetime'2012-10-01T00:00:00Z'%20and%20
    EndDate%20eq%20datetime'2013-12-31T23:59:59Z'&
  $top=2&
  $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/MailTrafficSummary</id>
  <title type="text">MailTrafficSummary</title>
  <updated>2013-02-09T20:06:36Z</updated>
  <link rel="self" title="MailTrafficSummary" href="MailTrafficSummary" />
  <entry>
    <id>https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailTrafficSummary(0)</id>
    <category term="TenantReporting.MailTrafficSummaryReport" 
      scheme="https://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" title="MailTrafficSummaryReport" href="MailTrafficSummary(0)" />
    <title />
    <updated>2013-02-09T20:06:36Z</updated>
    <author>
      <name />
    </author>
    <content type="application/xml">
      <m:properties>
        <d:C1>userone@example.onmicrosoft.com</d:C1>
        <d:C2>3185</d:C2>
        <d:C3 m:null="true" />
      </m:properties>
    </content>
  </entry>
  <entry>
    <id>https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailTrafficSummary(0)</id>
    <category term="TenantReporting.MailTrafficSummaryReport" 
      scheme="https://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" title="MailTrafficSummaryReport" href="MailTrafficSummary(0)" />
    <title />
    <updated>2013-02-09T20:06:36Z</updated>
    <author>
      <name />
    </author>
    <content type="application/xml">
      <m:properties>
        <d:C1>usertwo@example.onmicrosoft.com</d:C1>
        <d:C2>352</d:C2>
        <d:C3 m:null="true" />
      </m:properties>
    </content>
  </entry>
</feed>

The following shows the same results in JSON format.

  {
    "d":
      [
          {
            "__metadata":
              {
                "id":"https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailTrafficSummary(0)",
                "uri":"https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailTrafficSummary(0)",
                "type":"TenantReporting.MailTrafficSummaryReport"
              },
            "C1":"userone@example.onmicrosoft.com",
            "C2":"3185",
            "C3":null
          },
          {
            "__metadata":
              {
                "id":"https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailTrafficSummary(0)",
                "uri":"https://reports.office365.com/ecp/ReportingWebService/Reporting.svc/MailTrafficSummary(0)",
                "type":"TenantReporting.MailTrafficSummaryReport"
              },
            "C1":"usetwo@example.onmicrosoft.com",
            "C2":"352",
            "C3":null
          }
      ]
  }

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 MailTrafficSummary 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 MailTrafficTop report returns the same information as the Get-MailTrafficSummaryReport 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.

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.